Error codes - Circle Docs

When an error is encountered, CPN returns an error code and a message. The sections below show an explanation of each error code returned by the API, and steps to resolve (where possible). For error response shapes and general errors that can be returned by any Circle API, see API errors.

Common

Status code	Error code	Detail	Description
`500`	`-1`	`UNKNOWN_ERROR`	A generic response for errors that aren’t properly handled.
`400`	`2`	`API_PARAMETER_INVALID`	API request was missing parameters or had incorrect parameter types.
`403`	`3`	`FORBIDDEN`	The client is recognized but does not have permission to access the resource. Resolution: Verify the IP allowlist for the API key has the correct permissions through your Circle representative.
`401`	`4`	`UNAUTHORIZED`	The client did not provide valid authentication credentials to access the resource. Resolution: Verify your API key was passed as a `Bearer` token in the `Authorization` header of the API request.
`404`	`2`	`RESOURCE_NOT_FOUND`	The requested resource could not be found.
`400`	`2900000`	`INVALID_TENANCY_ENV`	The parameter and the environment of the API call doesn’t match (for example, a testnet chain in the production environment). Resolution: Update the request body to use the correct parameters.

Quote

Status code	Error code	Detail	Description
`400`	`290100`	`AMOUNT_OUTSIDE_LIMIT`	The provided amount does not fall in the supported range. It either exceeds the `cryptoLimit` or `fiatLimit`. Resolution: Make a request to the configuration endpoint to determine supported combinations and try your request again with different parameters.
`400`	`290101`	`BFI_NOT_AVAILABLE`	Only one BFI services the requested route and that service is unavailable. Resolution: Retry your request at a later time.
`400`	`290102`	`ROUTE_NOT_SUPPORTED`	The route includes unsupported countries. Resolution: Make a request to the configuration endpoint to determine supported combinations and try your request again with different parameters.

Payment

Status code	Error code	Detail	Description
`400`	`290200`	`QUOTE_NOT_FOUND`	The provided quote ID can’t be found. Resolution: Verify the quote ID is correct and make a new API request.
`400`	`290201`	`QUOTE_ALREADY_IN_USE`	The provide quote ID has been used to create another payment. Resolution: Request a new quote and use it to create your payment.
`400`	`290202`	`QUOTE_EXPIRED`	The quote used to request payment creation is expired. Resolution: Request a new quote and use it to create your payment.
`400`	`290203`	`INVALID_SENDER_ADDRESS_BLOCKCHAIN`	The blockchain associated with `senderAddress` does not match the requested blockchain from the quote. Resolution: Use the same blockchain in the payment request body as the `senderAddress`.
`400`	`290204`	`SANCTIONED_SENDER_WALLET_ADDRESS`	The provided wallet address is on sanctioned lists.
`400`	`290205`	`PENDING_RFI_VERIFICATION`	An RFI was requested for the sender or recipient so the payment can’t be created. Resolution: Complete the RFI for the requested information before creating another payment.
`400`	`290206`	`RFI_REJECTED`	The given sender or receiver has a rejected RFI with the given BFI and the payment can’t be completed.
`400`	`290207`	`REQUIRED_PARAMETER_MISSING`	A required parameter is missing in the request data. Resolution: Check the error in the response and make a new request with the missing parameter.
`400`	`290208`	`COMPLIANCE_INFORMATION_REJECTED`	The compliance information provided was rejected.

Transaction

Status code	Error code	Detail	Description
`400`	`290300`	`ACTIVE_TRANSACTION_ALREADY_EXISTS`	The payment already has an associated active or complete transaction. Resolution: For payments with an existing active transaction, sign and submit the transaction instead of attempting to create a new one.
`400`	`290301`	`BLOCKCHAIN_UNSUPPORTED`	The sender address blockchain is not supported by CPN for creating transactions. Resolution: Use the blockchain indicated in the quote.
`400`	`290302`	`BLOCKCHAIN_UNSUPPORTED_FOR_V2`	The blockchain is not support for Transactions V2. Resolution: See supported blockchains for the complete list of supported blockchains.
`400`	`290303`	`INVALID_TRANSACTION_STATUS_FOR_SUBMISSION`	The transaction provided is not in a submittable status. Resolution: Only submit a transaction when it is in the `CREATED` state.
`400`	`290304`	`INVALID_PAYMENT_STATUS`	The transaction can’t be submitted due to an invalid payment state. Resolution: Only submit a transaction when the payment is in the `CRYPTO_FUNDS_PENDING` state.
`400`	`290305`	`PAYMENT_NOT_FOUND`	The payment ID provided in the request was not found.
`400`	`290306`	`TRANSACTION_NOT_FOUND`	The transaction provided by the resource ID in the path was not found.
`400`	`290307`	`SIGNED_TRANSACTION_SUBMITTED`	A signed transaction for the payment has already been submitted. Resolution: Wait for the transaction to reach a terminal state.
`400`	`290308`	`PAYMENT_EXPIRED`	The payment is expired. Resolution: Request a new quote, then create a new payment and submit the transaction in the appropriate time frame.
`400`	`290309`	`SIGNED_TRANSACTION_EXPIRED`	The signed transaction is expired. Solana requires that you submit signed transactions in 150 blocks (~1 min) of signing them. Resolution: Create a new transaction for the same payment and sign and submit it in the appropriate time frame.
`400`	`290310`	`NONCE_TOO_LOW`	The nonce for the signed transaction is lower than the current wallet nonce. Resolution: Resubmit the signed transaction with the current wallet nonce.
`400`	`290311`	`SIGNED_TRANSACTION_PAYLOAD_MISMATCH`	The signed transaction payload does not match the CPN payment. For EVM chains, the EIP-3009 typed data must match the value in the `messageToBeSigned` field returned from the create transaction endpoint. For Solana, the signed transaction object must match the value from the `messageToBeSigned` field. Resolution: Resubmit the transaction with the correct payload.
`400`	`290312`	`INSUFFICIENT_TOKEN_BALANCE`	The sender’s wallet does not have enough USDC to complete the transfer. Resolution: Add USDC to the wallet and resubmit the signed transaction.
`400`	`290313`	`INSUFFICIENT_GAS_BALANCE`	The sender’s wallet does not have enough native tokens to cover the gas cost of the transaction. Resolution: Add native tokens to the wallet and resubmit the signed transaction.
`400`	`290314`	`PAYMENT_ID_MISMATCH`	The payment ID provided in the signed data does not match the expected value.
`400`	`290315`	`GAS_PRICE_TOO_LOW`	The gas price in the signed transaction is below network thresholds. The fee must exceed the estimated high fee to ensure prompt confirmation. Resolution: Sign the transaction with a higher gas price and resubmit.
`400`	`290316`	`NONCE_MISMATCH`	When resubmitting the transaction, the wallet address or nonce does not match the original submission. Sign the transaction with the same wallet and nonce as the previous transaction and resubmit.
`500`	`290317`	`FULL_NODE_SERVICE_UNAVAILABLE`	The full node used by CPN is unavailable or returning an unexpected error during transaction validation. Resolution: Submit the signed transaction at a later time.
`400`	`290318`	`PAYMENT_REF_ID_ONCHAIN`	The payment ref ID has already been used onchain. The signed transaction may have been rebroadcast prior to submission to CPN. Resolution: Contact Circle customer support to reconcile the transaction.
`400`	`290319`	`OUT_OF_GAS`	For EVM chains, the gas limit in the signed transaction is insufficient to cover the execution costs. For Solana, the allocated compute budget falls short of the transaction’s requirements, preventing execution. Resolution: For EVM chains, increase the gas limit. For Solana, increase the compute budget. Create a new transaction for the same payment and sign and submit it.
`400`	`290320`	`NONCE_ALREADY_USED`	The nonce has already been used by the same sender in another signed transaction submission. Resolution: Resubmit the signed transaction using the next available nonce.
`400`	`290321`	`INVALID_TRANSACTION_SIGNATURE`	The transaction signature is invalid. Resolution: Review the guidelines for signing a transaction and try again with updated signing functions.
`400`	`290322`	`SANCTIONED_WALLET_ADDRESS`	The wallet address used is on a sanction list.
`400`	`290324`	`CROSS_CHAIN_UNSUPPORTED`	The crosschain transfer is not supported by CPN. Resolution: Make a request to the configuration endpoint to determine supported combinations and try your request again with different parameters.
`400`	`290325`	`COMPLETED_TRANSACTION_EXISTS`	A completed transaction already exists. No need to accelerate.
`400`	`290327`	`INVALID_SIGNED_TX`	The signed transaction can’t be decoded or is otherwise invalid. Resolution: Review the guidelines for signing a transaction and try again with updated signing functions.
`400`	`290328`	`ONCHAIN_ACCOUNT_NOT_FOUND`	The Solana account specified in the transaction is not found. Resolution: Ensure the Solana account has been initialized before using it as the sender address for the transaction.
`400`	`290329`	`TRANSACTION_EXPIRED`	The transaction is expired. Resolution: Create a new transaction and submit it in the appropriate time frame.
`400`	`290330`	`CREATED_PENDING_TRANSACTION_EXIST_AT_ACCELERATION`	The existing transaction is not signed or submitted yet before the current attempt to accelerate it. Resolution: Sign the existing transaction or wait for the signed transaction to be broadcast.
`400`	`290331`	`NO_TRANSACTION_TO_ACCELERATE`	No broadcast transaction to be accelerated.
`400`	`290332`	`ONCHAIN_ACCOUNT_INVALID`	An invalid Solana address was used to create the transaction. Resolution: Verify the sender account provided in the request is a valid Solana address capable of signing and sending transactions. Don’t use system accounts or program accounts. Resubmit the request using a valid Solana account.
`400`	`290333`	`BROADCASTING_IN_PROGRESS`	A submitted transaction is already in a non-terminal state. Resolution: Wait for the result.
`400`	`290334`	`NONCE_TOO_HIGH`	The transaction nonce exceeds the permitted range relative to the current nonce. Resolution: Check your wallets latest nonce and make sure the nonce selected for your transaction does not exceed that value by more than 32. If you are sending multiple concurrent transactions for multiple payments, try waiting for the previous few transactions to settle.
`400`	`290336`	`INCOMPATIBLE_QUOTE`	The quote is incompatible with the specified transaction. The quote’s `transactionVersion` must match the transaction flow you use. Resolution: Make sure the `transactionVersion` specified in the endpoint response is consistent with the transaction flow you are using.
`400`	`290337`	`PAYMENT_MISSING_BLOCKCHAIN_ADDRESS`	The payment is missing the sender blockchain address. Resolution: Make sure you create the payment with `blockchain` and `senderAddress`.
`400`	`290340`	`INSUFFICIENT_ALLOWANCE_TO_PERMIT2`	The ERC-20 allowance granted to the `Permit2` contract is insufficient to cover the total required token amount for the payment, including both the payment amount and associated fees. Resolution: With your sender wallet, approve the `Permit2` contract to spend the required amount of USDC for the payment.
`400`	`290341`	`PERMIT2_NONCE_ALREADY_USED`	The `Permit2` nonce included in the typed data for the sender has already been used. Resolution: Create a new transaction for the same payment with the same sender address, then sign and submit it.
`400`	`290352`	`ONCHAIN_SETTLEMENT_CUTOFF_TIME_EXCEEDED`	The signed transaction was submitted after the onchain settlement cutoff. The cutoff time is the payment’s expiry time minus a blockchain-specific buffer (for example, ~19 minutes for Ethereum, ~8 minutes for Polygon PoS, ~25 seconds for Solana, and ~0.5 seconds for Arc). Resolution: Request a new quote, create a new payment, and submit the signed transaction before the cutoff time.

RFI

Status code	Error code	Detail	Description
`400`	`290400`	`RFI_EXPIRED`	The RFI has expired; you can’t submit data to an expired resource. Resolution: Create a new payment for the user and complete a new RFI.
`400`	`290401`	`RFI_NOT_SUBMITTABLE`	Requirement data submissions are limited to RFIs with the `INFORMATION_REQUIRED` status. Submission for an RFI in any other status results in this error code.
`400`	`290402`	`RFI_FILE_NOT_FOUND`	The uploaded filename does not match the file input name specified in the request for information. Resolution: Ensure the correct files are uploaded and that the file names exactly match those specified in the RFI.
`400`	`290403`	`RFI_FILE_INVALID_CONTENT`	The server was unable to read the content of the uploaded file. Resolution: Ensure the uploaded file contains content in a compatible format that can be processed by the CPN server.
`400`	`290404`	`RFI_FILE_CONTENT_TOO_LARGE`	The size of the uploaded file exceeds the maximum allowed size. Resolution: Ensure that the uploaded file does not exceed the 10 MB.
`400`	`290405`	`RFI_UNSUPPORTED_FILE_TYPE`	The MIME type of the uploaded file is not supported. Resolution: Ensure that the uploaded file has a MIME type accepted by the file upload endpoint.

Encryption

Status code	Error code	Detail	Description
`400`	`290500`	`ENCRYPTED_BLOB_DECRYPTION_ERROR`	The decryption process failed. Resolution: Ensure the correct public key was used to encrypt the payload.
`400`	`290502`	`INVALID_JWE_FORMAT`	The JWE compact payload is not formatted correctly or is missing required components. Resolution: Ensure you’re using a standard library for encrypting the payload and sending in the JWE compact format.
`400`	`290503`	`UNSUPPORTED_ENCRYPTION_ALGORITHM`	The JWE compact payload was not encrypted with a supported algorithm. Resolution: Ensure your encryption function is correctly implementing the appropriate algorithms and resubmit.

Support ticket

Status code	Error code	Detail	Description
`400`	`290600`	`TICKET_REFERENCE_REQUIRED`	Ticket reference ID is required for escalation.
`404`	`290601`	`ORIGINAL_TICKET_NOT_FOUND`	The original ticket was not found with the provided reference ID.
`400`	`290602`	`INVALID_SUPPORT_TICKET_ISSUE_TYPE`	Issue type is not allowed for this origin. Resolution: Ensure the correct issue type is provided.
`404`	`290603`	`PAYMENT_NOT_FOUND_FOR_TICKET`	The payment ID provided was not found.
`500`	`290604`	`SUPPORT_TICKET_SALESFORCE_CREATION_FAILED`	Failed to create a ticket in Circle Salesforce. Resolution: Try again at a later time.
`500`	`290605`	`SUPPORT_TICKET_BFI_CREATION_FAILED`	Failed to create a BFI support ticket. Resolution: Try again at a later time.

​Common

​Quote

​Payment

​Transaction

​RFI

​Encryption

​Support ticket