About our API response codes

In order to simplify integration, we have tried to standardize the response codes that we return across our APIs. While not every API will necessarily return every response code, every API will adhere to the same meanings for the same response codes and – for errors – the same response formatting and semantic content.

Success

In the case of success, you will need to see the documentation for each API to see details on how the response is formatted and what API-specific data each contains. A delivery date response is very different than a carrier selection response, for instance. You can find a list of our APIs with a brief description of what they do in Shipium's APIs.

All successes will have the same response codes.

Success responses

HTTP response code	Meaning	Contents
200 (OK)	Success. The action you intended to take succeeded, and/or the data you requested will be available in the body of the response.	API-specific JSON containing information pertaining to the specific request; each API's documentation will have more details about what the nature of this content is.
204 (No Content)	Success with no response. This is a rare use case, but you should regard a 204 as a success and expect no additional content beyond headers.	(None)

Client and server error responses

In the case of failures from any Shipium API, you will always get one of the following return codes for the cases described, though not every API necessarily returns all of the return codes based on its operation. Likewise, every error will return data in the same format, though additional data may also be passed for certain error cases.

Error responses

Error responses fall into two groups based on the nature of the issue:

4XX. Client errors. Something in the nature of the request that was made prevents it from being completed. Examples include bad or missing data or lack of access to the data requested. These should generally be fixable by the caller.
5XX. Server errors. Something has gone wrong on the Shipium side of things, preventing us from responding to the request. Waiting and trying again may be successful, but the underlying reason does not appear to be related to details of the request made.

HTTP response code	Meaning	Contents
400 (Bad Request)	Missing required values or badly formatted input values	Details about the nature of the missing or incorrect values encountered
401 (Unauthorized)	You will receive a 401 most commonly if you attempt to either (1) access APIs without having first authenticated or (2) attempting to utilize a service that your company is not authorized to use (e.g., not paying for).	Make sure that you are following the pattern laid out in Authentication.
403 (Forbidden)	You will receive a 403 if you are authenticated but attempting to access data to which the authenticated credentials do not have access. For instance, if you authenticated as CompanyOne but tried to access a shipment that was part of CompanyTwo's account, you will receive a 403 response code.	Make sure that you are following the pattern laid out in Authentication.
404 (Not Found)	This is generally an issue with a bad ID (shipment ID, label ID, etc.) or a bad route.	Details about the ID that could not be found
429 (Too Many Requests)	You will only see a 429 if you have increased your call volume to a degree that it looks like a DDOS attack. You should not expect to see this in practice other than maybe as a pass-through from a carrier while running in test mode.	Details about the volumes seen relative to allowable volumes
500 (Internal Server Error)	A 500 means that something bad has happened and it was our fault. It is possible that retrying a 500 error will succeed.	Details about the nature of the internal error; for 500 errors, an additional boolean field retry will exist with a value of `true` for those errors for which a retry is warranted and `false` if a retry is unlikely to succeed.
502 (Bad Gateway)	A 502 may be returned if a required external resource is unavailable and no backup (cache, secondary resource, etc.) is available.	Details about the nature of the external entity that returned this error
503 (Service Unavailable)	A 503 may be returned during certain timeframes in which the service has been taken offline for some reason. This should be very rare.	Details about why the service is unavailable and when it is expected to be available again, if known
504 (Gateway Timeout)	Similar to a 502, but specifically related to timeouts from required external resources	Details about the nature of the external entity that caused this error

Error response format

{
  "timestamp": "2020-11-07T01:08:41.934+00:00",
  "status": XXX,
  "error": "XXX STANDARD_HTTP_LABEL",
  "message": "Useful information",
  "path": "/api/v1/path/that/was/called\"
}

Field	Data	Data format
timestamp	Timestamp for the error	ISO 8601 datetime
status	HTTP status code	3-digit HTTP status code
error	HTTP label for the error	Standard HTTP label, such as `OK`, etc..
message	Details of the error that has occurred for debugging and investigation purposes	Free-form message containing details of the error and any relevant data or IDs associated with the failed request.
path	The API path that was called as part of the error, including any data embedded as part of the request (e.g., IDs)	Valid URL that was called and resulted in the error

Resources

Your Shipium team member is available to help along the way. However, you might find these resources helpful: