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).
| 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. |
| Status code | Error code | Detail | Description |
|---|---|---|---|
400 | 290100 | AMOUNT_OUTSIDE_LIMIT | The provided amount does not fall within 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. |
| 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. |
| 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 | 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 within the appropriate timeframe. |
400 | 290309 | SIGNED_TRANSACTION_EXPIRED | The signed transaction is expired. Solana requires that you submit signed transactions within 150 blocks (~1 min) of signing them. Resolution: Create a new transaction for the same payment and sign and submit it within the appropriate timeframe. |
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 currently 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 within the appropriate timeframe. |
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. |
| 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. Submissions for an RFI in any other status will result in this error code. |
| 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. |
| 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. |
Did this page help you?
© 2023-2025 Circle Technology Services, LLC. All rights reserved.
