Overview

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.

However, all successes will have the same response codes.

Success responses

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 every 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

Broadly, the 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.

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\"
}