Errors Guide

This guide explains how to identify and handle errors returned by the EasyPost API, including HTTP status codes, error response structures, and common error codes.

• Review the Getting Started Guide for an introduction to the EasyPost API.
• Become familiar with EasyPost API operations and Client Libraries.
• Understand basic HTTP status codes and error handling.

EasyPost communicates errors using standard HTTP status codes and returns a JSON response with additional details about the error.

• 400 Bad Request: The request was not processed due to a client error.
• 401 Unauthorized: Authentication is required and has failed.
• 402 Payment Required: There is a lack of billing information or insufficient funds.
• 403 Forbidden: The request was valid, but the server is refusing to respond to it.
• 404 Not Found: The requested resource could not be found.
• 405 Method Not Allowed: The request method is not supported for the requested resource.
• 422 Unprocessable Entity: The request was well-formed, but the server was unable to process the provided data.
• 429 Too Many Requests: The user has sent too many requests in a given amount of time.
• 500 Internal Server Error: An unexpected error occurred on the server.
• 503 Service Unavailable: The server is currently unable to handle the request due to temporary overloading or maintenance.

The EasyPost API returns error details in a structured JSON response. Error responses can include the following fields:

• code: A machine-readable string that identifies the error.
• message: A human-readable description of the error.
• errors: An array containing additional error details. Items can be structured objects or strings, depending on the error.

EasyPost Client Libraries encapsulate API errors and raise exceptions for client errors, server errors, and exceptional conditions such as network failures. Handle exceptions appropriately based on the application’s requirements.

API errors can return the errors field in one of two formats:

• Array of objects: Each item contains structured error details, such as a message field.
• Array of strings: Each item contains the error message directly as a string.

Check the type of each item in the errors array before accessing its value. When an item is an object, access the error message using a field such as error.errors[0][“message”]. When an item is a string, access the value directly using error.errors[0].

For production error handling, account for both formats rather than assuming a single response shape.

1curl -X POST https://api.easypost.com/v2/shipments \
2  -u "$EASYPOST_API_KEY": \
3  -H 'Content-Type: application/json' \
4  -d '{
5    "shipment": {}
6  }'

1{
2  "error": {
3    "code": "ADDRESS.VERIFY.FAILURE",
4    "message": "Address not found",
5    "errors": [
6      {
7        "field": "address",
8        "message": "Address not found",
9        "suggestion": null
10      },
11      {
12        "field": "street1",
13        "message": "House number is missing",
14        "suggestion": null
15      }
16    ]
17  }
18}

Visit the EasyPost Help Center for FAQs, troubleshooting guidance, and additional support resources.