Error Codes

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

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.

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

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.