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.

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

JSON

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

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:

error	message	constraints
value_must_be_true	field1 must be true (was false)	NA
value_must_be_false	field1 must be false (was true)	NA
required	field1 may not be null (was null)	NA
not_required	field1 must be null (was foo)	NA
min_value	field1 must be greater than or equal to 2 (was 0)	"constraints": { "min": 2 }
min_value	field1 must be greater than 2.0 (was 2.0)	"constraints": { "min": "2.0", "inclusive": false }
max_value	field1 must be less than or equal to 99 (was 1024)	"constraints": { "max": 99 }
max_value	field1 be less than or equal to 99.99 (was 100)	"constraints": { "max": "99.99", "inclusive": true }
length_outside_bounds	field1 must be between 2 and 5 (was qwerty)	"constraints": { "min": 2, "max": 5 }
pattern_mismatch	field1 must match “[a-z]+” (was 123456)	"constraints": { "pattern": "[a-z]+" }
date_not_in_past	field1 must be in the past (was 2020-08-31T18:18:54.211Z)	NA
date_not_in_future	field1 must be in the future (was 2020-08-31T18:18:17.621Z)	NA
number_format	field1 numeric value out of bounds (<3 digits>.<2 digits> expected) (was 123.456)	"constraints": { "max-integral-digits": 3, "max-fractional-digits": 2 }

API error format

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

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. For example, if you fail to supply a value for a required field, you’ll receive the following error response:

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

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

Key	Description	optional
error	type of an error	false
message	human-friendly message	false
location	period-separated path to the property that causes this error. An example could be field1 or address.billingCountry	false
invalidValue	actual value of the property specified in location key, as received by the server	true
constraints	special object that contains additional details about the error and could be used for programmatic handling on the client side	true

List of API error codes

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

Code	Message	Description
-1	Unknown Error	An unknown error occurred processing the API request
1	Malformed authorization. Is the authorization type missing?	API Key is missing or malformed
2	Invalid Entity	Error with the JSON object passed in the request body
3	Forbidden	API Key used with request does not have one of the roles authorized to call the API endpoint
1077	Payment amount is invalid	Payment amount must be greater than zero
1078	Payment currency not supported	An invalid currency value was used when making a payment
1083	Idempotency key already bound to other request	The idempotency key used when making a request was used with another payment. Please retry with a different value
1084	This item cannot be canceled	A cancel or refund request cannot be canceled
1085	This item cannot be refunded	A cancel or refund request cannot be refunded
1086	This payment was already canceled	This payment was already canceled
1087	Total amount to be refunded exceeds payment amount	Total amount to be refunded exceeds payment amount
1088	Invalid source account	An invalid source account was specified in a payout or transfer request
1089	The source account could not be found	Unable to find the source account specified in a payout or transfer request
1093	Source account has insufficient funds	The source account has insufficient funds for the payout or transfer amount
1096	Encryption key id could not be found	An encryption key id must be provided if request includes encrypted data
1097	Original payment is failed	Attempting to cancel or refund a failed payment
1101	Invalid country format	An invalid ISO 31660-2 country code was provided
1106	Invalid district format	Invalid district format, must be a 2 character value
1107	Payout limit exceeded	Payout can’t be accepted as it would exceed the given limit
1108	Unsupported Country	Country not supported for customer
1143	Checkout session not found	The checkout session id passed in the request doesn’t exist in the DB
1144	Checkout session is already in a completed state	The checkout session cannot be extended because it is already in a complete state
2003	The recipient address already exists	The blockchain address has already been associated with the account
2004	The address is not a verified withdrawal address	The blockchain address must first be verified before it can be used as a destination in a transfer request
2005	The address belongs to an unsupported blockchain	The blockchain type used as a transfer destination is not supported
2006	Wallet type is not supported	The wallet type specified when creating an end user wallet is not supported
2007	Unsupported transfer	A transfer from the provided source to the provided destination is not supported
5000	Invalid travel rule identity type	The provided identity type must be either “individual” or “business”
5001	Payout not found	Payout doesn’t exist based on the ID provided. Please check the payout id
5002	Invalid payout amount	Payout amount must be more than 0
5003	Inactive destination address	Cannot send payout to an inactive destination address. If you have just added the address, you may have to wait for 24 hours before use
5004	Destination address not found	The destination address for this payout could not be found
5005	Source wallet not found	Source wallet for this payout could not be found
5006	Insufficient funds	The source wallet has insufficient funds for this payout
5007	Unsupported currency	Currency not supported for this operation
5011	Invalid destination address	Can’t send payout to an invalid destination address
5012	Invalid destination location types	Can’t search for both crypto and fiat payouts
5013	Invalid source wallet id	Source wallet id must be a number for payouts search
5014	The address is not valid for the blockchain	Provided blockchain address is not valid for the corresponding blockchain
5015	Invalid destination chain	Provided blockchain address has an invalid chain in respect to the currency used
500000	Unsupported currency for reporting daily user balance	User provided a currency other than USDC or EURC
500001	Custody balance asOfDate is too far from today’s date	asOfDate provided was before or after today’s date
500002	Custody balance cannot be less than zero	Negative balances were provided
500003	Local custody balance can’t be greater than total custody balance	Total balance must be greater than or equal to local balance
500004	Idempotency key can’t be reused	The same idempotency key was used for different requests
500005	Custody balance report already exists	A custody balance report was already created for the provided date and currency. Contact customer care for edits.

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

Code	Description
payment_failed	Payment failed due to an unknown reason
payment_fraud_detected	Suspected fraud detected by Issuing bank. Please instruct your user to contact their bank directly to resolve
payment_denied	Payment denied by Circle Risk Service, see payment riskReasonCode for more details
payment_not_supported_by_issuer	Issuer bank was unable to process the transaction
payment_not_funded	There were insufficient funds to cover the payment amount
payment_stopped_by_issuer	A stop has been placed by the issuer or customer
payment_canceled	Payment was canceled
payment_failed_balance_check	Payment failed the Plaid balance check due to insufficient funds
payment_unprocessable	The provided encryptedData could not be processed

Payout Error Codes

Code	Description
insufficient_funds	Insufficient funds
transaction_failed	Transaction failed due to an unknown reason
payout_canceled	The payout was canceled

Transfer Error Codes

Code	Description
transfer_failed	The transfer failed due to unknown reasons
transfer_denied	The transfer was denied by Circle Risk Service, see transfer riskEvaluation for more details
blockchain_error	There was an error processing the transfer on-chain
insufficient_funds	There was not enough funding to cover the transfer amount