# Errors Guide

## Overview

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.

---

## Prerequisites

- 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.

Related:

- [Getting Started Guide](https://docs.easypost.com/guides/getting-started)
- [Client Libraries](https://docs.easypost.com/libraries)

---

## HTTP Status Codes

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.

## Error Response Structure

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.

## Error Handling

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.

## Catching an Error

[Content omitted: API request and response examples. Review the rendered documentation for complete request payloads, response payloads, and code samples.]

Related:

- [Error Object](https://docs.easypost.com/docs/errors#error-object)
- [FieldError Object](https://docs.easypost.com/docs/errors#fielderror-object)

---

## General API Error Codes

| Code | Description |
|---|---|
| INTERNAL_SERVER_ERROR | An internal server error occurred. Retry the request. Contact support@easypost.com if the error continues. |
| NOT_ACCEPTABLE | The requested response format is not supported by the resource. |
| NOT_FOUND | The requested resource was not found. |
| FORBIDDEN | Access to the requested resource is forbidden. |
| PAYMENT_REQUIRED | The account has insufficient funds. Review the account billing settings. |
| UNAUTHORIZED | Authentication failed or the provided credentials do not permit access to the resource. |
| BAD_REQUEST | The request is malformed or contains invalid data. |
| PAYMENT_GATEWAY.ERROR | The payment processor could not complete the request. Retry the request or contact support@easypost.com if the error continues. |
| MODE.UNAUTHORIZED | A production API key is required to access this resource. |
| MODE.CONFLICT | The API key mode does not match the requested resource or parameter mode. |
| DATE.PARSE.FAILURE | One or more dates are incorrectly formatted and could not be parsed. |
| PARAMETER.FORBIDDEN | The request contains one or more parameters that are not permitted. |
| PARAMETER.REQUIRED | A required parameter is missing. |