Error Handling

When errors occur, ShipEngine gives you the information you need to successfully handle the error and resolve the problem.

HTTP Status Codes

All HTTP responses include an HTTP status code, which signals whether the reqeusted 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 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.

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
{
  "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"
    }
  ]
}

Request ID

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.

Error Structure

Each error object inside the errors array has the following structure:

Property Name	Description
`error_source`	Indicates where the error originated and/or who you should contact for support. Some errors come from third-party sources, such as shipping carriers or sales order sources.
`error_type`	The type of error. This can be used to handle all errors of a certain type the same way.
`error_code`	A code that indicates the specific error that occurred.
`message`	A description of the error. This is useful for logging or debugging, but you should not code against this field as messages can change over time.
error-specific fields	Many errors have additional fields that provide more context about the error. Theses fields can be used for additional programmatic error-handling behavior. But be sure your code allows for these fields to be `null` or absent.

See our Error Codes page for a complete list of the possible values for each of these fields.

Here's an example of an error object. Notice that it has all of the error fields, plus some error-specific fields like confirmation, carrier_id, carrier_code, and carrier_name.

1
2
3
4
5
6
7
8
9
10
{
  "error_source": "shipengine",
  "error_type": "business_rules",
  "error_code": "confirmation_not_supported",
  "message": "Adult signature confirmation is not supported by Australia Post.",
  "confirmation": "adult_signature",
  "carrier_id": "se-123456",
  "carrier_code": "australia_post",
  "carrier_name": "Australia Post"
}

CORS Errors

ShipEngine does not support CORS (Cross Origin Resource Sharing). If you are using ShipEngine from a web app or mobile app, please review our authentication guidelines for client applications.