When errors occur, ShipEngine gives you the information you need to successfully handle the error and resolve the problem. This page shows you how.
HTTP Status Codes
All HTTP responses include an HTTP status code, which signals whether the reqeusted operation was successful or not.
If the request was entirely or partially successful, then you'll get a
2XX status code, such as
201 Created, or
204 No Content. You should still check the
errors array to determine whether any part of the request failed.
4XX status code, such as
400 Bad Request,
404 Not Found or
409 Conflict, indicates that the API request was invalid in some way. These errors always mean that you will need to change some part of the request before retrying it again. Perhaps there's a syntax error, or a required field is missing, or the API key is invalid. Check the
errors array to see exactly what's wrong.
If an error occurs on ShipEngine's servers or on a third-party server such as a carrier or marketplace, then you'll get a
5XX response. Examples include
500 Internal Server Error and
503 Service Unavailable. These errors usually aren't due to anything wrong with your API request. It's most likely a server-side problem.
The Errors Array
JSON responses include an
errors field, which is an array of any errors that occurred. If the operation was entirely successful, then the
errors array will be empty. But if part or all of the operation failed, then the
errors array will contain one or more error objects.
Here's an example of a response with errors. Notice that there are two error objects in the
As you can see in the example above, the response also includes a
request_id field. This is a unique ID that we assign to all API calls. If you ever need to contact us for support, you can reference the
request_id of the API call in question. This will allow our support team to quickly find the problem and assist you in resolving it.
Each error object inside the
errors array has the following structure:
Here's an example of an error object. Notice that it has all of the error fields, plus some error-specific fields like