The error codes used by Circle APIs fall into two categories, API response errors and entity errors. API response errors are returned immediately in response to API requests. Entity errors are associated with API entities such as payments and generally take seconds or minutes to return.

API Error Responses

When an API request is made and the error is known immediately, Circle APIs will return the appropriate HTTP status code along with a JSON error response. Because HTTP status codes do not always provide sufficient information about the cause of an error, Circle’s API response errors provide more detailed JSON responses to help you determine what’s gone wrong.

In the example below, the request is missing a required field. The HTTP Status code in this case would be HTTP/1.1 400 Bad Request

{"code":2,"message":"Invalid entity.
metadata.email may not be empty (was null)","errors":[{"error":"invalid_value","location":"metadata.email","message":"metadata.email may not be empty (was null)"}]}

API Error Types

You can automate the handling of certain error types. These include the following error names, which include example messages and constraints, where applicable:

API Error Format

Whenever an API request results in an error, the JSON response will contain both a high-level error code and a human-readable message within the body.

HTTP/1.1 400 Bad Request
Content-Type: application/json

{
 "code": 2,
 "message": "Invalid entity.\n[<error-message1>...\n<error-messageN>]"
}

Extended error format

In some cases, you’ll receive extended information about why a request has failed.

Example: If you fail to supply a value for a required field, you’ll receive the following error response:

HTTP/1.1 400 Bad Request
Content-Type: application/json

{
 "code": 2,
 "message": "Invalid entity.\nfield1 may not be null (was null)",
 "errors": [
   {
     "error": "required",
     "message": "field1 may not be null (was null)",
     "location": "field1",
     "invalidValue": "null",
     "constraints": {} # see below for details
   }
 ]
}

This extended error response contains one or more associated error descriptions. Error description attributes can be read as follows:

List of API Error Codes

The table below shows the list of JSON error codes that may be returned in an API error response.

Entity Error Responses

With entities such as payments, cards, bank wires, and transfers, an error is generally not known immediately, so no error code can be returned at the time of the request.

For instance, when making a payment, the transaction is processed asynchronously and the create payment request will have a status of pending. After processing, the status will eventually be set to approved or failed.

API entities such as payments and cards are processed asynchronously after the initial create request is made. If a problem occurs while processing the request (the status is shown as failed), the errorCode property is set on the entity and can be retrieved either by polling the GET endpoint or via a notification. The response explains why the payment was unsuccessful.

Here are some Entity error codes associated with payments, cards, bank wires, and transfers.

Payment Error Codes

Card Verification Error Codes

Payout Error Codes

Transfer Error Codes