Circle APIs: API and Entity Errors

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.

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 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)"
    }
  ]
}

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

Whenever an API request results in an error, the JSON response contains both an error code and a human-readable message in the body.

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

In some cases, you'll receive extended information about why a request has failed. For example, if you fail to supply a value for a required field, you'll receive the following error response:

{
  "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": {}
    }
  ]
}

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

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

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.