Errors

In the event of a client or server error, the response will contain a 4xx or 5xx status code, respectively, accompanied by a well-formed JSON body describing the issue, e.g., a required field was omitted.

Each client library will encapsulate these errors and raise an exception, in addition to other exceptional cases, such as network failures. It is recommended to handle exceptions gracefully and to report any issues to support@easypost.com.

List of Error Codes

Error object

code

string

Machine-readable description of the problem

message

string

Human-readable description of the problem

errors

FieldError or string array

Breakdown of errors for specific fields in the request. Errors can be returned as an array of objects or strings and must be handled accordingly

Error Object

{
  "code": "ADDRESS.VERIFY.FAILURE",
  "message": "Address not found",
  "errors": [
    {
      "field": "address",
      "message": "Address not found",
      "suggestion": null
    },
    {
      "field": "street1",
      "message": "House number is missing",
      "suggestion": null
    }
  ]
}

FieldError object

field

string

Field of the request that the error describes

message

string

Human-readable description of the problem

suggestion

string

Occasional insight on how to correct the error

FieldError Object

{
  "field": "street1",
  "message": "House number is missing",
  "suggestion": null
}

AddressVerificationFieldError object

code

string

Machine-readable description of the problem

field

string

Field of the request that the error describes

message

string

Human-readable description of the problem

suggestion

string

Occasional insight on how to correct the error

AddressVerificationFieldError Object

{
  "field": "address",
  "message": "Address not found",
  "suggestion": null
}

Common HTTP Status Codes

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.