4xxerrors are client errors, which are informative and actionable. They communicate a mistake to the user and suggest fixes.5xxerrors are unexpected server-side errors.
Description column.
General error format
HTTP status codes do not always provide sufficient information to determine the cause of the error. Since the status code is part of the header of the response, the body of response contains additional, Circle-specific, error information. For example, if a request contains an invalid parameter, the response includes the following: HeaderHTTP/1.1 400 Bad RequestContent-Type: application/json
Body
JSON
Extended error format
In some cases, the response includes extended information about the cause of the error. For example, if a request doesn’t include a value for a required parameter, the response includes a detailed error message: HeaderHTTP/1.1 400 Bad RequestContent-Type: application/json
Body
JSON
General errors
This section describes some common extended error messages you might encounter using Wallets and Contracts APIs. The following errors are general errors that can be returned for any request.| Error Code | HTTP code | Error Message | Description |
|---|---|---|---|
-1 | 400 | Something went wrong | An unknown error occurred while processing the API request. |
3 | 403 | Forbidden | The API key used does not have access to the requested endpoint. |
Invalid requests
A400 HTTP status code indicates that the request is invalid or malformed.
When the request is invalid, the Circle-specific error code is 2. The
following table describes the common error messages that can be returned for
invalid requests.
| Error Code | HTTP code | Error Message | Description |
|---|---|---|---|
2 | 400 | Invalid Entity | There is an error in the JSON format passed in the request. |
2 | 400 | Fail to bind request to parameter: invalid UUID format | The parameter must be in UUID format. |
2 | 400 | Error: Field validation | One of the fields in the request is invalid. |
2 | 400 | Error: Field validation for blockchain failed on the blockchain tag | The blockchain does not exist. Try again with a supported blockchain. |
2 | 400 | Error: Field validation for gasLimit failed on the required_without tag | If feeLevel is provided, gasLimit should be set to NULL. If feeLevel is NULL, gasLimit must be provided. |
2 | 400 | Error: Field validation for parameter failed on the min tag | The parameter is not in the correct format. |
2 | 400 | Cannot unmarshal | The JSON body of the request is not valid. |
2 | 400 | INVALID: parameter empty | The parameter is required for this request. Try the request again with this parameter. |
Wallets errors
This section describes the errors that can be returned for Programmable Wallet API requests.User errors
| Error code | HTTP code | Error message | Description |
|---|---|---|---|
155101 | 409 | Existing user already created with the provided userId. | The user ID already exists. Try the request again with a different user ID. |
155102 | 404 | Cannot find the user id in the system. | The user is not found. Try the request again with a different user ID. |
155103 | 401 | Cannot find the user token in the system. | The user token is not found. Try the request again with a different user token. |
155104 | 403 | The userToken had expired. | The user token has expired. Generate a new user token and try the request again. |
155105 | 403 | The userToken is invalid. | The user token is invalid. Generate a new user token and try the request again. |
155106 | 409 | The user had already been initialized. | The user has already been initialized. Query the user status first to check if the user has already set a pin and created a wallet. |
155107 | 409 | User has previously set a PIN. Use PUT /user/pin to reset the PIN. | The PIN has already been set successfully. Query the user status to check if the user has already set a PIN. |
155108 | 409 | User has previously set up their security questions, and they can't be reset. | The user has already set the security questions successfully. The questions can only be set once. |
155109 | 409 | The specified user has been disabled. | The specified user has been disabled. |
155110 | 400 | User has not set up a PIN yet. | The action cannot be performed before the user sets their pin. To set a pin, call initialize or set a pin first. |
155111 | 400 | User hasn't set the security questions for PIN backup yet. | The action cannot be performed before the user sets their security questions. To set security questions, call initialize or set security questions first. |
155112 | 400 | The user has inputted the incorrect pin. | The user’s PIN is not correct. Try the request again with a different PIN. |
155113 | 400 | Provided device ID is not found in the system. | The device ID is not correct. Try the request again with a different device ID. |
155114 | 400 | Provided app ID is not recognized in the system. | The app ID is not found. Check the app ID in the SDK API. If you do not have the app ID or it is incorrect, you can acquire it from the Developer Console or by making an API request to GET /config/entity. |
155115 | 400 | The user has inputted the incorrect security answers | The provided security answers are not correct. Try the request again with different answers. |
155116 | 404 | The challenge ID doesn't exist in the system. | The challenge ID is invalid. Check the challenge ID in the SDK API. |
155117 | 400 | The content provided for approval is not correct. | The provided approval content is unknown. Integrate with the latest SDK. |
155118 | 400 | Encryption key does not match with the user's token. Call POST /users/token to get the correct token encryption key pair. | The encryption key does not match the user’s token. Call POST /users/token to get the correct token encryption key pair. |
155119 | 400 | The user's PIN input is locked. It will be unlocked after the cooldown period. | The user’s PIN input is locked. Wait for the cooldown period to unlock, and try again. |
155120 | 400 | The user's security questions input is locked. It will be unlocked after the cooldown period. | The user’s security questions input is locked. Wait for the locked period to expire to unlock, and try again. |
155121 | 403 | The provided challengeId has expired. | The challenge has expired. Try the request again to create a new challenge. |
155122 | 403 | The provided challengeId is invalid | The challenge is invalid. Try the request again to create a new challenge. |
155123 | 403 | No extra information provided when adding PIN-related requests. | When SDK approves the challenge, the challenge format is wrong. Try the request again to create a new challenge. |
155124 | 403 | The extra information provided for PIN-related requests is invalid. | When SDK approves the challenge, the challenge format is wrong. Try the request again to create a new challenge. |
155130 | 400 | User OTP token is expired. | User OTP token is expired. Request an OTP email again. |
155131 | 400 | User OTP token is invalid. | User OTP token is invalid. Check the input parameters. |
155132 | 404 | User OTP value is not found. | User OTP value is not found. Request an OTP email first. |
155133 | 400 | User OTP value is invalid. | User OTP value is invalid. Check the input parameters. |
155134 | 400 | User OTP value is not matched. | User OTP value is not matched. Check if the OTP value and OTP token match. |
155135 | 400 | User's email is invalid. | User’s email is invalid. Check the email format in the request. |
155136 | 400 | User's email is not matched. | User’s email is not matched. Check if the email is the same. |
155137 | 400 | User's device ID is invalid. | User’s device ID is invalid. Check the input parameters. |
155138 | 400 | Failed to send the email. | Failed to send the email. Check the SMTP configuration in the developer console. |
155139 | 400 | The idToken / accessToken of SSO is expired. | The idToken / accessToken of SSO is expired. Get it from the SSO provider again. |
155140 | 400 | Failed to validate the idToken/ accessToken. | Failed to validate the idToken / accessToken. Ensure the ID input on the SSO provider configuration is correct. |
155141 | 400 | The user has exceeded the max limit (5) of entering OTP at the moment. | The user has exceeded the max limit (5) of entering OTP at the moment. Wait for a cool-down period of 60 minutes before attempting again. |
155142 | 400 | The max limit (5) of sending OTP has been exceeded at the moment. | The max limit (5) of sending OTP has been exceeded at the moment. Wait for a cool-down period of 60 minutes before attempting again. |
155143 | 400 | The device token is expired. | The device token is expired. Request a new device token, and note that the expiry time is 10 minutes. |
155144 | 400 | The device token is invalid. | The device token is invalid. Request a new device token, and ensure it is the correct token. Note that only one active token is allowed per deviceId. |
155145 | 404 | The device token is not found. | The device token is not found. Request a new device token to proceed. |
155146 | 400 | The OTP token is invalid as the user has entered it incorrectly three times. | The OTP token is invalid as the user has entered it incorrectly three times. Request a new OTP email. |
Entity errors
| Error code | HTTP code | Error message | Description |
|---|---|---|---|
155150 | 404 | The SMTP server configuration is not found. | The SMTP server configuration is not found. Complete the SMTP setting in the developer console first. |
155151 | 400 | The SMTP server configuration is invalid. | The SMTP server configuration is invalid. Check the SMTP setting in the developer console. |
155152 | 404 | The SSO provider configuration is not found. | The SSO provider configuration is not found. Add the SSO provider in the developer console. |
155154 | 400 | The OTP email template is invalid. | The OTP email template is invalid. Check the OTP email template configuration. |
155155 | 404 | The OTP email template is not found. | The OTP email template is not found. Add the OTP email template in the developer console first. |
155156 | 400 | Failed to update the email template. | Failed to update the email template. Check the content of the OTP email template. |
155157 | 400 | Failed to update the SMTP server | Failed to update the SMTP server configuration. Check the SMTP setting in the developer console. |
Transaction errors
| Error code | HTTP code | Error message | Description |
|---|---|---|---|
155201 | 400 | Not enough funds to fulfill the withdraw request. | There is insufficient native token balance in the wallet to cover all pending transactions on the network. Add funds to the wallet, and try again. |
155202 | 400 | Transaction nonce is inconsistent with sender's latest nonce. | Transaction nonce mismatches occur when a sender has created one or more transactions onchain where the initial transaction has not yet reached finality. Try the transaction again. |
155203 | 400 | User op nonce can not be larger than 0 when smart contract wallet hasn't been deployed. | User op nonce can not be larger than 0 when the smart contract wallet hasn’t been deployed. |
155204 | 400 | The total cost of executing transaction is higher than the balance of the user's account when estimating fee. | There is insufficient native token balance in the wallet to cover the total cost of executing the transaction. Add funds to the wallet, and try again. |
155205 | 400 | Failed to execute this request on EVM due to insufficient token when estimating fee. | There is insufficient non-native token balance in the wallet to cover the request execution. Add funds to the wallet, and try again. |
155206 | 400 | The sender address is not token owner or approved when estimating token transfer. | The owner of the tokens may not call approve ABI to allow the caller to access the tokens. |
155207 | 400 | Gas required exceeds allowance when estimating fee. | Gas required exceeds allowance when estimating fee. |
155208 | 400 | Estimate fee execution reverted. | Estimate fee execution reverted on EVM. |
155209 | 400 | ABI function signature can't pack ABI parameter. | The ABI parameters were invalid. Correct the ABI parameters and try again. |
155210 | 400 | Fails to perform transaction estimation. | Estimate fee execution failed on EVM. |
155211 | 400 | MaxFee * GasLimit exceed configurable max transaction fee (default is 1 native token). | Reduce maxFee or gasLimit, and try again. Note Circle has system-wide limits for maxFee for each blockchain network and native token pair. Ethereum = 1 ETH, Polygon = 10 MATIC, Avalanche = 1 AVAX. |
155215 | 400 | Unsupported operation for transaction. | The requested operation for the transaction is not eligible to be executed anymore. Check the status of the transaction. |
155218 | 400 | Invalid number of nft in transaction request. | Invalid number of NFT in the transaction request. Only ERC-1155 supports batch NFT token transfer. |
155219 | 400 | Invalid destination address. | Correct the destination address, and try again. |
155220 | 400 | Wallet and token's blockchain mismatch. | The wallet and token’s blockchain must be the same. |
155221 | 400 | Invalid amounts in transfer request. | Other than ERC-1155, all other types of token transfer amount length should be 1. |
155222 | 404 | NFT metadata can not be found. | NFT metadata can not be found. |
155223 | 400 | Unsupported userId for get transactions. | UserId is not supported as a query parameter for GET transaction requests. |
155224 | 400 | Failed to parse the provided amounts in request to decimals. | Failed to parse the provided amounts in request to decimals. |
155225 | 400 | Wallet and request's blockchain mismatch. | The wallet and blockchain in the request should be the same. |
155226 | 400 | Invalid source address. | Correct the source address, and try again. |
155227 | 400 | Invalid transaction type. | Transaction validation failed because the transaction type is not outbound. |
155228 | 400 | Missing token ID. | The token ID is missing from the request. Add the correct token ID, and try again. |
155229 | 400 | Transaction is not eligible for operation. | The transaction is not eligible for operation. |
155230 | 400 | No call data or abi signature provided. | Provide an ABI signature, and try again. |
155231 | 400 | Transaction needs feeLevel or gasLimit provided. | Provide feeLevel or gasLimit, and try again. |
155232 | 400 | SCA transaction needs feeLevel provided. | SCA transaction needs feeLevel provided. Specify the feeLevel, and try again. |
155233 | 400 | Provided gasLimit is too low to complete the requested transaction. | Provided gasLimit smaller than network estimation. Provide a higher gasLimit, and try again. |
155234 | 400 | Transaction can't have both feeLevel and fee parameters provided. | Specify either feeLevel, or provide the detailed fee parameters for a transaction. |
155235 | 400 | EIP1559 chains need maxFee/priorityFee provided. | EIP1559 chains need maxFee/priorityFee provided. |
155236 | 400 | Failed to parse the provided fee in request to decimals. | Failed to parse the provided fee in request to decimals. |
155237 | 400 | PriorityFee cannot be larger than maxFee in creating transaction request. | PriorityFee cannot be larger than maxFee in creating transaction requests. |
155238 | 400 | Non-EIP1559 chains need gasPrice provided. | Non-EIP1559 chains need gasPrice provided. |
155239 | 400 | Invalid token address for transfer. | Correct the token address, and try again. |
155240 | 400 | Invalid token standard for transfer. | Correct the token standard, and try again. |
155241 | 400 | Invalid token decimal for transfer. | Correct the token decimal, and try again. |
155242 | 400 | The lengths of amounts and nft tokens don't match. | The lengths of amounts and NFT tokens don’t match. |
155243 | 400 | Missing bytecode for contract deployment. | Provide bytecode for contract deployment, and try again. |
155244 | 400 | Cannot provide both WalletID and SourceAddress/Blockchain. | Specify WalletID or provide the SourceAddress/Blockchain, and try the request again. |
155245 | 400 | Invalid amount in contract execution request. | Invalid amount in contract execution request. Error raised when parsing amount in the request. |
155247 | 400 | Cannot provide both CallData and AbiFunctionSignature/AbiParameters. | Specify CallData or provide AbiFunctionSignature/AbiParameters, and try the request again. |
155264 | 400 | Wait for pending transactions to be included on the blockchain before submitting new requests. EVM chains restrict the number of queued transactions per sender address. | Wait, as you have reached the maximum number of pending transactions per sender address for the corresponding chain. You can check the status of your transactions using the GET /transactions endpoint. To expedite processing, consider using multiple wallets to distribute your transactions. (see Transaction Limits and Optimizations for more tips.) |
Wallet errors
| Error code | HTTP code | Error message | Description |
|---|---|---|---|
155501 | 409 | Frozen wallets can not be updated or interact with, only query. | Frozen wallets cannot be updated or interacted with. You can only query this wallet. |
155502 | 403 | Max amount of wallets (tentative 1M) reached under 1 wallet set. | 1M maximum amount of wallets has been reached under 1 wallet set. |
155503 | 400 | Metadata array length needs to match wallet count in create developer wallets request. | The metadata array length must match the wallet count in the POST /developer/wallets request. |
155504 | 400 | Metadata array length needs to match number of blockchains in create user wallets request. | The metadata array length must match the number of blockchains in the create user wallet request. |
155505 | 400 | SCA wallet needs to wait for first-time transaction to be queued before processing more transactions. | SCA wallet needs to wait for first-time transactions to be queued before processing more transactions. |
155506 | 400 | SCA wallet config is invalid. | SCA wallet config is invalid. |
155507 | 400 | SCA account is not supported on the given blockchain. | The SCA account type is not supported on the given chain. See the account types doc for more details on the supported blockchains. |
155508 | 400 | Can't create multiple user-controlled SCA wallets across multiple blockchains at a time. | When the account type is SCA, you cannot send more than one value in the blockchains array. Instead, send two separate requests, providing blockchain value one in the first request and value two in the second request. |
155509 | 400 | Entity needs to setup paymaster policy on Mainnet before SCA account creation. Please check paymaster policy setup | The paymaster policies for your account need to be properly configured. Go to the web3 console and ensure you have a policy configured for the blockchain and do not have multiple policies for a given blockchain. |
155510 | 400 | The operation is not supported on the blockchain you specify. | The provided wallet is associated with a blockchain that does not support the requested API operation. Ensure you are using a compatible wallet and refer to the documentation for a list of supported operations. |
155511 | 400 | Blockchain is not supported for wallet creation. | The specified blockchain is not supported for wallet creation. See the list of supported blockchains. |
155512 | 404 | The owner of the SCA wallet can not be found. | The SCA wallet owner cannot be found. Check if ownership was transferred or if the account is set up correctly. |
155515 | 400 | The provided wallet account type is not supported by this API. | The specified wallet account type is not supported by this API. See account types for a list of supported types. |
Wallet set errors
| Error code | HTTP code | Error message | Description |
|---|---|---|---|
155601 | 400 | Failed to retrieve wallet set which already exists. | Cannot create a new wallet set because it already exists. Try again with a unique wallet set. |
SDK UI errors
| Error code | HTTP code | Error message | Description |
|---|---|---|---|
155701 | N/A | User canceled | The user canceled or exited the execute UI. |
155702 | N/A | <Launch UI failed reason> | Check the error message to see the exact UI launch failure reason. |
155703 | N/A | The code you entered is not the same as the first one | The code you entered is not the same as the first one. |
155704 | N/A | Your PIN can't have repeating or consecutive numbers | Your PIN can’t have repeating or consecutive numbers. Try again with a valid PIN. |
155705 | N/A | Your hint can't be the same as the answer | Your hint can’t be the same as the answer. Try again with a valid hint. |
155706 | N/A | Network error | Network error. Try again. |
155707 | N/A | Failed to encrypt data | Failed to encrypt data. Try again. |
155708 | N/A | "Biometrics instead of PIN" is disabled | Enable the “Biometrics instead of PIN” SDK API. |
155709 | N/A | The device system doesn't support biometrics | Cannot enable biometrics in this device. The user must use the PIN code. |
155710 | N/A | Failed to decrypt biometrics key | Ask the user to reset the biometrics settings. |
155711 | N/A | The user has not enabled biometrics yet | The user skipped the biometrics setting. |
155712 | N/A | The user refused to enable biometrics | Must call the SetBiometricsPin SDK API so the user can enable biometrics. |
155713 | N/A | Too many requests. Try again later | Wait for 30 minutes, and try again. |
155714 | N/A | Too many requests. The biometrics sensor on the device is locked | Go to the device system settings to unlock. |
155715 | N/A | The user didn't enable biometrics | The user can be prompted to go to the App Settings to re-allow the app to use biometrics. (Warning) This operation will cause the app to be relaunched. |
155716 | N/A | Unexpected error for biometrics | Unexpected error. Try again. |
155717 | N/A | User secret is missing. Check the input parameters. | The user secret is missing from the request. Ensure the input parameters are correct and retry the operation. |
155718 | N/A | User token format is invalid | User token format is invalid. Ensure the format of the user token is correct, then perform login and execute the challenge again. |
155719 | N/A | User token and SDK API execute function do not match. Please ensure that executeWithUserSecret is for users with SSO/Email auth method, and execute is for users with PIN auth method. | User token and SDK API execute function do not match. Ensure that executeWithUserSecret is for users with SSO/email auth method, and execute is for users with PIN auth method. |
155720 | N/A | Social login failed | Social login failed. The social provider returns failed during the execution of social login flow. Refer to the error message for more details. |
155721 | N/A | Login info is missing | Login info is missing. Perform login and execute the challenge again. |
Sign transaction errors
| Error code | HTTP code | Error message | Description |
|---|---|---|---|
155801 | 400 | Transaction or rawTransaction is invalid. | Invalid transaction or rawTransaction in request. |
155802 | 400 | Account not found. | Cannot find account in the transaction header. |
155803 | 400 | Not signer account. | Account is not the signer of this transaction. |
155804 | 400 | Transaction is already signed. | Transaction is already signed. |
155805 | 400 | Transaction failed to deserialize. | Transaction failed to de-serialize. |
155806 | 400 | The transaction size exceeds blockchain limit. | The transaction size exceeds blockchain limit. |
155807 | 400 | The chain ID is not supported for signing. | The typed data or transaction chain ID is not supported for EVM signing |
155808 | 400 | The chain ID is missing in sign request. | The chain ID is missing from typed data or transaction for EVM signing. |
Common errors
| Error code | HTTP code | Error message | Description |
|---|---|---|---|
156001 | 404 | Cannot find target wallet in the system. Either the specified wallet doesn't exist or it's not accessible to the caller. | The specified wallet does not exist, or is not visible to the caller. Try the request again with a valid wallet ID. |
156002 | 404 | Cannot find target token in the system. Either the specified token doesn't exist or it's not accessible to the caller. | The specified token does not exist, or is not visible to the caller. Try the request again with a valid token ID. |
156003 | 404 | Cannot find target transaction in the system. Either the specified transaction doesn't exist or it's not accessible to the caller. | The specified transaction does not exist, or is not visible to the caller. Try the request again with a valid transaction ID. |
156004 | 400 | Reusing an entity secret ciphertext is not allowed. Please re-encrypt the entity secret to generate new ciphertext. | Reusing an entity secret ciphertext is not allowed. Re-encrypt the entity secret to generate a new ciphertext and try again. |
156005 | 404 | Cannot find target wallet set in the system. Either no such wallet set, or it's not accessible to the caller. | The specified wallet set does not exist, or is not visible to the caller. Try the request again with a valid wallet set. |
156006 | 400 | TEST_API key cannot be used with blockchain mainnets, or LIVE_API key cannot be used with blockchain testnets. | A TEST_API key cannot be used with blockchain Mainnets, and a LIVE_API key cannot be used with blockchain Testnets. Try again with a valid API key. |
156007 | 401 | TEST_API key or LIVE_API key is not found for the request. | A TEST_API key or LIVE_API key is not found for the request. Try again with a valid API key. |
156008 | 400 | Cannot find target entity config in the system. Either no such entity config, or it's not accessible to the caller. | The specified entity config does not exist, or is not visible to the caller. Try the request again with a valid entity config. |
156009 | 400 | Fail to parse id as UUID in url. | The specified id is invalid (must be in UUID format). Try again with a valid id. |
156010 | 404 | Cannot find the corresponding entity in the system. | The specified entity does not exist, or is not configured. Try again with a valid entity. |
156011 | 404 | Cannot find target nftTokenId in the system. | The nftTokenId does not exist. Try again with a valid nftTokenId. |
156012 | 404 | Cannot find corresponding pagination cursor in the system. | The pagination parameters are invalid. Correct your pagination parameters, and try again. |
156013 | 400 | The provided entity secret is invalid. | The specified entity secret is not valid. Create or re-encrypt your entity secret, and try again. |
156014 | 400 | Pagination params are invalid. Only UUID format is supported for pageBefore and pageAfter. | Pagination parameters are invalid. Only UUID format is supported for pageBefore and pageAfter. |
156015 | 409 | The secret for this entity has already been set. | The secret for this entity has already been set. |
156016 | 403 | The entity secret has not been set yet. Please provide encrypted ciphertext in the console. | The entity secret has not been set yet. Provide encrypted ciphertext in the Developer console. |
156017 | 400 | The specified blockchain parameters are incorrect. | The blockchain parameters are invalid. Correct the blockchain parameters, and try again. |
156018 | 403 | The uploaded recovery file is invalid. | The uploaded recovery file is invalid. Try again with a valid recovery file. |
156019 | 403 | Current entity secret is invalid. Please rotate the entity secret first. | The current entity secret is invalid. Rotate the entity secret first in the Developer console, and try again. |
156020 | 403 | Please use a new idempotency key. | Use a new idempotency key, and try again. |
156021 | 409 | A new wallet set ID is required. | Use a new wallet set ID, and try again. |
156023 | 409 | EncodedByHex is true in sign request, but the message is not hex encoded. | The encodedByHex parameter is set to true, but the provided message is not in the correct hex-encoded format. Ensure the message is hex-encoded and try again, or set encodedByHex to false. |
156024 | 400 | Data is not a valid JSON string in sign request. | Data is not a valid JSON string in the Sign request. Provide a valid JSON format typed data string. |
156025 | 400 | Invalid message in request. | Sign message is invalid. Try the request again with a valid EIP-191 message. |
156026 | 400 | Invalid typed data in request. | Typed data is invalid. Try the request again with a valid EIP-712 typed data. |
156027 | 400 | The specified blockchain is either not supported or deprecated. | Try again with a supported blockchain. See the guide Supported blockchains for the complete list of supported blockchains. |
156030 | 400 | Invalid unsigned delegate action in request. | Invalid unsigned delegate action in request. |