Errors

When something is wrong with a request, the API will respond with a non-200 status code.

To help you better understand the problem, where possible, the API overloads a number of different HTTP error codes. Additional information is provided by way of subcodes and cause strings, so your application logic has as much visibility as possible into what has gone wrong.

All HTTP responses include an HTTP status code, which signals whether the requested operation was successful or not.

2XX
If the request was entirely or partially successful, then you'll get a 2XX status code, such as 200 OK, 201 Created, or 204 No Content. You should still check the errors array to determine whether any part of the request failed.

4XX
A 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.

5XX
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 errors array.

{
  "request_id": "5a8d3073-2626-4a64-983d-29c5d55dce5e",
  "errors": [
    {
      "error_source": "shipengine",
      "error_type": "business_rules",
      "error_code": "unspecified",
      "message": "carrier_id se-12345 not found",
      "field_name": "carrier_id",
      "field_value": "se-12345"
    },
    {
      "error_source": "shipengine",
      "error_type": "validation",
      "error_code": "invalid_field_value",
      "message": "Invalid service_code",
      "field_name": "service_code",
      "field_value": "carrier_pigeon"
    }
  ]
}