API Errors

There are two categories of error codes you may encounter when using Circle APIs. The first is an error returned in response to an API request API Response Errors and the second is an error associated with an API entity such as a payment Entity Errors.

API Error Responses

In cases where an API request is made and the error can be detected immediately, a error response will be returned along with an appropriate HTTP status code. An example given below would be when 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)"}]}

See API Response Errors for more information on the error response format and a description of all error codes.

Entity Errors

In other cases an error cannot be returned at the time of the request. An example would be making a payment, where the response for the create payment request will have a status of pending.
The payment is processed asynchronously and the status will eventually be set to approved or failed. In this case where it is failed, subsequent calls to the GET /payment/{id} endpoint will return a response with an errorCode property indicating the reason why the payment was unsuccessful.
See Entity Errors for a description of error codes that can be associated with payments, cards, bank wires and transfers.