Meet ShipEngine’s New & Improved Error Codes

You probably know how it works already: 

You make an API call—and then you get an HTTP response. 

Each HTTP response includes a status code. 

These status codes sometimes indicate that you’ve encountered an error. It might look something like this:

"error_code":  "confirmation_not_supported",

But HTTP error codes alone are too broad and don’t always give you enough information to know what went wrong—or how to solve the problem. That’s why ShipEngine includes detailed error information in the HTTP response, so that developers and integrators using our API can get better information when things aren’t working properly.

Below, find an explanation of different types of HTTP error codes and the types of detailed error information you get when using ShipEngine. 

Different Types of HTTP Responses

HTTP error codes are included among general status codes that are organized in five levels. Those five levels are:

• 1xx: 100-level codes are informational in nature. They include 100 (for “continue”), 101 (for “switching protocols”), and many others.
• 2xx: 200-level codes indicate success. They include 200 (for “OK”), 201 (for “created”), and 204 (for “no content”).
• 3xx: 300-level codes are for redirections, like 304 (for “not modified”).
• 4xx: 400-level codes are reserved for client errors. If you get a 400-level error code (like 400 for “bad request” or 403 for “forbidden”), you’ve made some sort of invalid API request. The errors should help you change the request before trying again.
• 5xx: 500-level codes mean a server error—like 500 (for “internal server error) and 502 (for “bad gateway”). If you get a 500-level error, you’ve likely done nothing wrong—the problem is almost always on the server side.

Error Components

When an error occurs during a ShipEngine API call, you get back a JSON response. This response includes several components, including information about relevant errors. The following 6 components are included in the JSON response:

• Request ID (“request_id”): All ShipEngine API calls generate a unique identification code. This unique request ID can be referenced when you contact our support team.
• Error Source (“error_source”): The error source field helps you pinpoint where the error came from. For example, errors sometimes emerge from third parties like carriers.
• Error Type (“error_type”): The error type is a broader category into which your error fits. For example, your error type might relate to account status or to security. That information will be included here.
• Error Code (“error_code”): The error code tells you the specific type of error that occurred. These error codes are now much more informational and helpful than they were just recently within ShipEngine.
• Message (“message”): Messages are designed to provide greater context around the error. Again, the messages included in ShipEngine error codes are now much more informational than they once were.
• Error Specific Fields: Some errors have additional information that developers and integrators need. In these cases, error-specific fields may be used to share that additional information.

The JSON response will always include an “errors” array, even if everything was successful. If the array is empty, then there were no errors. 

ShipEngine Error Codes

Creating the best developer experience is one of our foremost goals at ShipEngine. That’s why we invested time and energy into revamping our error codes so that they provide more valuable information.

You can find in our documentation a complete rundown of error sources, error types, and error codes you might encounter when using ShipEngine.

Error sources include:

• ShipEngine (“shipengine”)
• carrier (“carrier”)
• order source (“order_source”)

Error types include:

• account status (“account_status”) 
• security (“security”) 
• validation (“validation”)
• business rules (“business_rules”)
• system (“system”) 

The list of specific error codes includes more than 30 different notifications you can receive when using ShipEngine. Check out our Error Codes in the ShipEngine documentation to see the full list. 

We’re Here to Help!

You’re never alone when integrating with ShipEngine. Our support team is here to help you no matter the challenge you’re facing—error-related or otherwise.

All you need to get started is a free API key. Get your API key now, and start using ShipEngine to solve shipping.