Circle APIs: API and Entity Errors
Troubleshoot and fine-tune your code using Circle’s detailed error responses.
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:
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 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:
key | meaning | 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 |
1032 | Account number is invalid or missing | An invalid number was provided when creating a card |
1051 | Payment not found | The payment id requested was not found |
1068 | Merchant account not associated with a marketplace | Attempting to create a marketplace payment with a merchant that is not associated with the marketplace |
1069 | A wallet account could not be found | Unable to find the wallet account referenced in a marketplace create payment request |
1070 | Marketplace info is required to create marketplace payment | Marketplace info was not provided with a marketplace create payment request |
1076 | Payment amount did not fall within merchant charge limits | The payment amount was greater than the maximum allowed limit or below the minimum allowed limit |
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 |
1091 | Invalid wire routing number | Could not find a bank with that routing number when creating wire bank account |
1092 | Invalid IBAN | Invalid IBAN used in request to create a wire bank account |
1093 | Source account has insufficient funds | The source account has insufficient funds for the payout or transfer amount |
1094 | The billing last name cannot be empty | When creating a card or bank account the billing last name must be provided |
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 |
1098 | Wire payment amount failed | Wire payment must be greater than the minimum amount |
1099 | The merchantWalletId query parameter is missing | The merchantWalletId query parameter must be set in association with the walletId parameter to retrieve wallet settlements |
1100 | Invalid fiat account type | The fiat account is invalid for the attempted payout type (e.g. using a business account for a marketplace payout) |
1101 | Invalid country format | An invalid ISO 31660-2 country code was provided |
1102 | IBAN country mismatch | IBAN does not match the provided bank country code |
1103 | IBAN required | IBAN is required is this request |
1104 | Additional bank details required | There are additional bank details required for this request; details of which are provided in the response |
1105 | Additional billing details required | There are additional billing details required for this request; details of which are provided in the response |
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 |
1109 | Invalid bin range | No bin range found for the card |
1110 | Invalid card number | Card number is invalid |
1111 | Invalid issuer country | Issuer country is invalid |
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 does 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 currently supported for this operation |
5011 | Invalid destination address | cannot send payout to an invalid destination address |
5012 | Invalid destination location types | cannot 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 |
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 |
card_failed | The payment failed due to a problem with the card such as an incorrect card number |
card_invalid | The card number was invalid |
card_cvv_invalid | Incorrect CVV value provided |
card_expired | Card expired |
card_limit_violated | The amount or frequency of payments exceeded card limits |
card_not_honored | The issuing bank did not approve the payment |
card_account_ineligible | The card is not linked to an eligible bank account |
card_restricted | Transaction not permitted to cardholder. Issuer has declined the transaction because the card cannot be used for this type of transaction. Please instruct your user to use a different payment method |
unauthorized_transaction | The user has advised the bank that the payment was not authorized |
bank_account_ineligible | The account is not eligible and no other default account was found |
bank_transaction_error | The bank reported an error processing the transaction |
invalid_account_number | The account number is invalid or missing |
invalid_wire_rtn | The wire routing number is invalid |
ref_id_invalid | Push payment reference Id not recognized |
account_name_mismatch | Account name does not match Circle resource account name |
account_number_mismatch | Push payment account number does not match Circle resource account number |
account_ineligible | Ineligible fiat account due to invalid type or state |
customer_name_mismatch | Customer full name doesn't match sender name |
institution_name_mismatch | Institution name doesn't match sender name |
Card Verification Error Codes
Code | Description |
---|---|
verification_failed | Verification failed due to an unknown reason |
verification_fraud_detected | Card suspected to be used for fraud |
risk_denied | Card denied by Circle Risk Service, see riskEvaluation for more details |
verification_not_supported_by_issuer | Issuer bank was unable to process the transaction |
verification_stopped_by_issuer | A stop has been placed on the card |
card_failed | Verification failed due to a problem with the card such as the card number does not exist |
card_invalid | The card number was invalid |
card_address_mismatch | The billing address provided in the card creation request did not match the one recorded by the issuer bank |
card_zip_mismatch | The postal code provided in the card creation request did not match the one recorded by the issuer bank |
card_cvv_invalid | Incorrect CVV value provided |
card_expired | Card expired |
card_not_honored | The issuing bank did not authorize the card |
card_account_ineligible | The card is not linked to an eligible bank account |
card_limit_violated | The amount or frequency of payments exceeded card limits |
card_cvv_required | The cvv is either incorrect or missing |
three_d_secure_not_supported | 3DS transactions are not supported by the issuing bank |
three_d_secure_required | 3DS is required by the issuing bank |
three_d_secure_failure | The customer failed the 3DS authentication step |
three_d_secure_action_expired | The customer took too long to finish the 3DS process. This typically expires after 15 minutes |
three_d_secure_invalid_request | The 3DS request was submitted with invalid parameters |
Payout Error Codes
Code | Description |
---|---|
insufficient_funds | Exchange insufficient funds |
transaction_denied | The transaction was denied as the fiat account is not verified |
transaction_failed | Transaction failed due to an unknown reason |
transaction_returned | The transaction was returned |
bank_transaction_error | The bank reported an error processing the transaction |
fiat_account_limit_exceeded | The Fiat account limit exceeded |
invalid_bank_account_number | The bank account number is invalid or missing |
invalid_wire_rtn | The wire routing number is invalid |
sen_not_supported | account_number_to must be a valid SEN account |
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 |
Updated about 1 month ago