Errors Guide

This guide provides an approach to identifying and managing errors encountered with EasyPost API operations. A clear understanding of the error framework and error handling are important for seamless integration and continuous operation.

• Users should have an active EasyPost account.
• New users should refer to the Getting Started Guide for a foundational understanding.
• Understanding of EasyPost API operations and Client Libraries.
• Familiarity with HTTP status codes and error handling.

Errors are communicated through standard HTTP status codes with a JSON response detailing the issue.

• 400 Bad Request: The request has invalid syntax for the given content type.
• 401 Unauthorized: Required authentication by the authorization header has failed or is missing.
• 404 Not Found: The action or resource was not found.
• 422 Unprocessable Entity: The input was parsed correctly, but was invalid for another reason.
• 500 Internal Server Error: An unexpected condition was encountered.
• 503 Service Unavailable: A part of the service, or a third party that is required to complete the operation, is unavailable.

EasyPost’s API returns error information in a structured JSON format. Each error includes:

• code: A machine-readable string identifying the encountered error.
• message: Describes the error in a human-readable string.
• field: An array of objects to provide specific details about the error.

Each client library will encapsulate errors and raise an exception. This includes both client and server errors, as well as exceptional cases such as network failures. It is recommended to handle exceptions gracefully; to report issues, please contact our Support team.

1curl -X POST https://api.easypost.com/v2/addresses \
2  -u "$EASYPOST_API_KEY": \
3  -H 'Content-Type: application/json' \
4  -d '{
5  "address": {
6    "street1": "..."
7  },
8  "verify_strict": "true"
9}'

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}

1curl -X POST https://api.easypost.com/v2/addresses \
2  -u "$EASYPOST_API_KEY": \
3  -H 'Content-Type: application/json' \
4  -d '{
5  "address": {
6    "street1": "..."
7  },
8  "verify_strict": "true"
9}'

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}

Below is a list of common error codes, along with their descriptions. This list does not encompass all possible error codes. For more detailed information, or additional assistance, please contact our Support team.

In addition to the guidance provided in our Guides, EasyPost offers support to assist with FAQs, troubleshooting issues, and inquiries related to the EasyPost platform.

Please visit the Help Center for more information.