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



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

errormessageconstraints
value_must_be_truefield1 must be true (was false)NA
value_must_be_falsefield1 must be false (was true)NA
requiredfield1 may not be null (was null)NA
not_requiredfield1 must be null (was foo)NA
min_valuefield1 must be greater than or equal to 2 (was 0)`"constraints": { "min": 2 }`
min_valuefield1 must be greater than 2.0 (was 2.0)`"constraints": { "min": "2.0", "inclusive": false }`
max_valuefield1 must be less than or equal to 99 (was 1024)`"constraints": { "max": 99 }`
max_valuefield1 be less than or equal to 99.99 (was 100)`"constraints": { "max": "99.99", "inclusive": true }`
length_outside_boundsfield1 must be between 2 and 5 (was qwerty)`"constraints": { "min": 2, "max": 5 }`
pattern_mismatchfield1 must match \"[a-z]+\" (was 123456)`"constraints": { "pattern": "[a-z]+" }`
date_not_in_pastfield1 must be in the past (was 2020-08-31T18:18:54.211Z)NA
date_not_in_futurefield1 must be in the future (was 2020-08-31T18:18:17.621Z)NA
number_formatfield1 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.



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



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

keymeaningoptional
errortype of an errorfalse
messagehuman-friendly messagefalse
locationperiod-separated path to the property that causes this error. An example could be `field1` or `address.billingCountry`false
invalidValueactual value of the property specified in `location` key, as received by the servertrue
constraintsspecial object that contains additional details about the error and could be used for programmatic handling on the client sidetrue

## List of API Error Codes

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

CodeMessageDescription
-1Unknown ErrorAn unknown error occurred processing the API request
1Malformed authorization. Is the authorization type missing?API Key is missing or malformed
2Invalid EntityError with the JSON object passed in the request body
3ForbiddenAPI Key used with request does not have one of the roles authorized to call the API endpoint
1032Account number is invalid or missingAn invalid number was provided when creating a card
1051Payment not foundThe payment id requested was not found
1068Merchant account not associated with a marketplaceAttempting to create a marketplace payment with a merchant that is not associated with the marketplace
1069A wallet account could not be foundUnable to find the wallet account referenced in a marketplace create payment request
1070Marketplace info is required to create marketplace paymentMarketplace info was not provided with a marketplace create payment request
1076Payment amount did not fall within merchant charge limitsThe payment amount was greater than the maximum allowed limit or below the minimum allowed limit
1077Payment amount is invalidPayment amount must be greater than zero
1078Payment currency not supportedAn invalid currency value was used when making a payment
1083Idempotency key already bound to other requestThe idempotency key used when making a request was used with another payment. Please retry with a different value
1084This item cannot be canceledA cancel or refund request cannot be canceled
1085This item cannot be refundedA cancel or refund request cannot be refunded
1086This payment was already canceledThis payment was already canceled
1087Total amount to be refunded exceeds payment amountTotal amount to be refunded exceeds payment amount
1088Invalid source accountAn invalid source account was specified in a payout or transfer request
1089The source account could not be foundUnable to find the source account specified in a payout or transfer request
1091Invalid wire routing numberCould not find a bank with that routing number when creating wire bank account
1092Invalid IBANInvalid IBAN used in request to create a wire bank account
1093Source account has insufficient fundsThe source account has insufficient funds for the payout or transfer amount
1094The billing last name cannot be emptyWhen creating a card or bank account the billing last name must be provided
1096Encryption key id could not be foundAn encryption key id must be provided if request includes encrypted data
1097Original payment is failedAttempting to cancel or refund a failed payment
1098Wire payment amount failedWire payment must be greater than the minimum amount
1099The merchantWalletId query parameter is missingThe merchantWalletId query parameter must be set in association with the walletId parameter to retrieve wallet settlements
1100Invalid fiat account typeThe fiat account is invalid for the attempted payout type (e.g. using a business account for a marketplace payout)
1101Invalid country formatAn invalid ISO 31660-2 country code was provided
1102IBAN country mismatchIBAN does not match the provided bank country code
1103IBAN requiredIBAN is required is this request
1104Additional bank details requiredThere are additional bank details required for this request; details of which are provided in the response
1105Additional billing details requiredThere are additional billing details required for this request; details of which are provided in the response
1106Invalid district formatInvalid district format, must be a 2 character value
1107Payout limit exceededPayout can't be accepted as it would exceed the given limit
1108Unsupported CountryCountry not supported for customer
1109Invalid bin rangeNo bin range found for the card
1110Invalid card numberCard number is invalid
1111Invalid issuer countryIssuer country is invalid
1143Checkout session not foundThe checkout session id passed in the request doesn't exist in the DB
1144Checkout session is already in a completed stateThe checkout session cannot be extended because it is already in a complete state
2003The recipient address already existsThe blockchain address has already been associated with the account
2004The address is not a verified withdrawal addressThe blockchain address must first be verified before it can be used as a destination in a transfer request
2005The address belongs to an unsupported blockchainThe blockchain type used as a transfer destination is not supported
2006Wallet type is not supportedThe wallet type specified when creating an end user wallet is not supported
2007Unsupported transferA transfer from the provided source to the provided destination is not supported
5000Invalid travel rule identity typeThe provided identity type must be either "individual" or "business"
5001Payout does not foundPayout doesn’t exist based on the ID provided. Please check the payout id
5002Invalid payout amountPayout amount must be more than 0
5003Inactive destination addressCannot send payout to an inactive destination address. If you have just added the address, you may have to wait for 24 hours before use
5004Destination address not foundThe destination address for this payout could not be found
5005Source wallet not foundSource wallet for this payout could not be found
5006Insufficient fundsThe source wallet has insufficient funds for this payout
5007Unsupported currencycurrency not currently supported for this operation
5011Invalid destination addresscannot send payout to an invalid destination address
5012Invalid destination location typescannot search for both crypto and fiat payouts
5013Invalid source wallet idsource wallet id must be a number for payouts search
5014The address is not valid for the blockchainProvided blockchain address is not valid for the corresponding blockchain
5015Invalid destination chainProvided 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

CodeDescription
payment_failedPayment failed due to an unknown reason
payment_fraud_detectedSuspected fraud detected by Issuing bank. Please instruct your user to contact their bank directly to resolve
payment_deniedPayment denied by Circle Risk Service, see payment `riskReasonCode` for more details
payment_not_supported_by_issuerIssuer bank was unable to process the transaction
payment_not_fundedThere were insufficient funds to cover the payment amount
payment_stopped_by_issuerA stop has been placed by the issuer or customer
payment_canceledPayment was canceled
payment_failed_balance_checkPayment failed the Plaid balance check due to insufficient funds
payment_unprocessableThe provided `encryptedData` could not be processed
card_failedThe payment failed due to a problem with the card such as an incorrect card number
card_invalidThe card number was invalid
card_cvv_invalidIncorrect CVV value provided
card_expiredCard expired
card_limit_violatedThe amount or frequency of payments exceeded card limits
card_not_honoredThe issuing bank did not approve the payment
card_account_ineligibleThe card is not linked to an eligible bank account
card_restrictedTransaction 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_transactionThe user has advised the bank that the payment was not authorized
bank_account_ineligibleThe account is not eligible and no other default account was found
bank_transaction_errorThe bank reported an error processing the transaction
invalid_account_numberThe account number is invalid or missing
invalid_wire_rtnThe wire routing number is invalid
ref_id_invalidPush payment reference Id not recognized
account_name_mismatchAccount name does not match Circle resource account name
account_number_mismatchPush payment account number does not match Circle resource account number
account_ineligibleIneligible fiat account due to invalid type or state
customer_name_mismatchCustomer full name doesn't match sender name
institution_name_mismatchInstitution name doesn't match sender name

## Card Verification Error Codes

CodeDescription
verification_failedVerification failed due to an unknown reason
verification_fraud_detectedCard suspected to be used for fraud
risk_deniedCard denied by Circle Risk Service, see `riskEvaluation ` for more details
verification_not_supported_by_issuerIssuer bank was unable to process the transaction
verification_stopped_by_issuerA stop has been placed on the card
card_failedVerification failed due to a problem with the card such as the card number does not exist
card_invalidThe card number was invalid
card_address_mismatchThe billing address provided in the card creation request did not match the one recorded by the issuer bank
card_zip_mismatchThe postal code provided in the card creation request did not match the one recorded by the issuer bank
card_cvv_invalidIncorrect CVV value provided
card_expiredCard expired
card_not_honoredThe issuing bank did not authorize the card
card_account_ineligibleThe card is not linked to an eligible bank account
card_limit_violatedThe amount or frequency of payments exceeded card limits
card_cvv_requiredThe cvv is either incorrect or missing
three_d_secure_not_supported3DS transactions are not supported by the issuing bank
three_d_secure_required3DS is required by the issuing bank
three_d_secure_failureThe customer failed the 3DS authentication step
three_d_secure_action_expiredThe customer took too long to finish the 3DS process. This typically expires after 15 minutes
three_d_secure_invalid_requestThe 3DS request was submitted with invalid parameters

## Payout Error Codes

CodeDescription
insufficient_fundsExchange insufficient funds
transaction_deniedThe transaction was denied as the fiat account is not verified
transaction_failedTransaction failed due to an unknown reason
transaction_returnedThe transaction was returned
bank_transaction_errorThe bank reported an error processing the transaction
fiat_account_limit_exceededThe Fiat account limit exceeded
invalid_bank_account_numberThe bank account number is invalid or missing
invalid_wire_rtnThe wire routing number is invalid
sen_not_supportedaccount_number_to must be a valid SEN account

## Transfer Error Codes

CodeDescription
transfer_failedThe transfer failed due to unknown reasons
transfer_deniedThe transfer was denied by Circle Risk Service, see transfer `riskEvaluation` for more details
blockchain_errorThere was an error processing the transfer on-chain
insufficient_fundsThere was not enough funding to cover the transfer amount