Skip to main content
The Wallets and Contracts APIs return an HTTP status code when they encounter an error in an API request:
  • 4xx errors are client errors, which are informative and actionable. They communicate a mistake to the user and suggest fixes.
  • 5xx errors are unexpected server-side errors.
The tables in the following sections describe some of the common error messages you might encounter using the Wallets and Contracts APIs. Where possible, a suggested fix is provided in the 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: Header HTTP/1.1 400 Bad RequestContent-Type: application/json Body
JSON
{
  "code": 2,
  "message": "API parameter invalid"
}

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: Header HTTP/1.1 400 Bad RequestContent-Type: application/json Body
JSON
{
  "code": 2,
  "message": "API parameter invalid",
  "errors": [
    {
      "error": "required",
      "message": "fail to bind request to CreateWalletSetRequest: EOF",
      "location": "field1",
      "invalidValue": "null",
      "constraints": {}
    }
  ]
}

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 CodeHTTP codeError MessageDescription
-1400Something went wrongAn unknown error occurred while processing the API request.
3403ForbiddenThe API key used does not have access to the requested endpoint.

Invalid requests

A 400 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 CodeHTTP codeError MessageDescription
2400Invalid EntityThere is an error in the JSON format passed in the request.
2400Fail to bind request to parameter: invalid UUID formatThe parameter must be in UUID format.
2400Error: Field validationOne of the fields in the request is invalid.
2400Error: Field validation for blockchain failed on the blockchain tagThe blockchain does not exist. Try again with a supported blockchain.
2400Error: Field validation for gasLimit failed on the required_without tagIf feeLevel is provided, gasLimit should be set to NULL. If feeLevel is NULL, gasLimit must be provided.
2400Error: Field validation for parameter failed on the min tagThe parameter is not in the correct format.
2400Cannot unmarshalThe JSON body of the request is not valid.
2400INVALID: parameter emptyThe 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 codeHTTP codeError messageDescription
155101409Existing user already created with the provided userId.The user ID already exists. Try the request again with a different user ID.
155102404Cannot find the user id in the system.The user is not found. Try the request again with a different user ID.
155103401Cannot find the user token in the system.The user token is not found. Try the request again with a different user token.
155104403The userToken had expired.The user token has expired. Generate a new user token and try the request again.
155105403The userToken is invalid.The user token is invalid. Generate a new user token and try the request again.
155106409The 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.
155107409User 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.
155108409User 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.
155109409The specified user has been disabled.The specified user has been disabled.
155110400User 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.
155111400User 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.
155112400The user has inputted the incorrect pin.The user’s PIN is not correct. Try the request again with a different PIN.
155113400Provided device ID is not found in the system.The device ID is not correct. Try the request again with a different device ID.
155114400Provided 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.
155115400The user has inputted the incorrect security answersThe provided security answers are not correct. Try the request again with different answers.
155116404The challenge ID doesn't exist in the system.The challenge ID is invalid. Check the challenge ID in the SDK API.
155117400The content provided for approval is not correct.The provided approval content is unknown. Integrate with the latest SDK.
155118400Encryption 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.
155119400The 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.
155120400The 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.
155121403The provided challengeId has expired.The challenge has expired. Try the request again to create a new challenge.
155122403The provided challengeId is invalidThe challenge is invalid. Try the request again to create a new challenge.
155123403No 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.
155124403The 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.
155130400User OTP token is expired.User OTP token is expired. Request an OTP email again.
155131400User OTP token is invalid.User OTP token is invalid. Check the input parameters.
155132404User OTP value is not found.User OTP value is not found. Request an OTP email first.
155133400User OTP value is invalid.User OTP value is invalid. Check the input parameters.
155134400User OTP value is not matched.User OTP value is not matched. Check if the OTP value and OTP token match.
155135400User's email is invalid.User’s email is invalid. Check the email format in the request.
155136400User's email is not matched.User’s email is not matched. Check if the email is the same.
155137400User's device ID is invalid.User’s device ID is invalid. Check the input parameters.
155138400Failed to send the email.Failed to send the email. Check the SMTP configuration in the developer console.
155139400The idToken / accessToken of SSO is expired.The idToken / accessToken of SSO is expired. Get it from the SSO provider again.
155140400Failed to validate the idToken/ accessToken.Failed to validate the idToken / accessToken. Ensure the ID input on the SSO provider configuration is correct.
155141400The 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.
155142400The 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.
155143400The device token is expired.The device token is expired. Request a new device token, and note that the expiry time is 10 minutes.
155144400The 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.
155145404The device token is not found.The device token is not found. Request a new device token to proceed.
155146400The 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 codeHTTP codeError messageDescription
155150404The SMTP server configuration is not found.The SMTP server configuration is not found. Complete the SMTP setting in the developer console first.
155151400The SMTP server configuration is invalid.The SMTP server configuration is invalid. Check the SMTP setting in the developer console.
155152404The SSO provider configuration is not found.The SSO provider configuration is not found. Add the SSO provider in the developer console.
155154400The OTP email template is invalid.The OTP email template is invalid. Check the OTP email template configuration.
155155404The OTP email template is not found.The OTP email template is not found. Add the OTP email template in the developer console first.
155156400Failed to update the email template.Failed to update the email template. Check the content of the OTP email template.
155157400Failed to update the SMTP serverFailed to update the SMTP server configuration. Check the SMTP setting in the developer console.

Transaction errors

Error codeHTTP codeError messageDescription
155201400Not 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.
155202400Transaction 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.
155203400User 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.
155204400The 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.
155205400Failed 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.
155206400The 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.
155207400Gas required exceeds allowance when estimating fee.Gas required exceeds allowance when estimating fee.
155208400Estimate fee execution reverted.Estimate fee execution reverted on EVM.
155209400ABI function signature can't pack ABI parameter.The ABI parameters were invalid. Correct the ABI parameters and try again.
155210400Fails to perform transaction estimation.Estimate fee execution failed on EVM.
155211400MaxFee * 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.
155215400Unsupported operation for transaction.The requested operation for the transaction is not eligible to be executed anymore. Check the status of the transaction.
155218400Invalid number of nft in transaction request.Invalid number of NFT in the transaction request. Only ERC-1155 supports batch NFT token transfer.
155219400Invalid destination address.Correct the destination address, and try again.
155220400Wallet and token's blockchain mismatch.The wallet and token’s blockchain must be the same.
155221400Invalid amounts in transfer request.Other than ERC-1155, all other types of token transfer amount length should be 1.
155222404NFT metadata can not be found.NFT metadata can not be found.
155223400Unsupported userId for get transactions.UserId is not supported as a query parameter for GET transaction requests.
155224400Failed to parse the provided amounts in request to decimals.Failed to parse the provided amounts in request to decimals.
155225400Wallet and request's blockchain mismatch.The wallet and blockchain in the request should be the same.
155226400Invalid source address.Correct the source address, and try again.
155227400Invalid transaction type.Transaction validation failed because the transaction type is not outbound.
155228400Missing token ID.The token ID is missing from the request. Add the correct token ID, and try again.
155229400Transaction is not eligible for operation.The transaction is not eligible for operation.
155230400No call data or abi signature provided.Provide an ABI signature, and try again.
155231400Transaction needs feeLevel or gasLimit provided.Provide feeLevel or gasLimit, and try again.
155232400SCA transaction needs feeLevel provided.SCA transaction needs feeLevel provided. Specify the feeLevel, and try again.
155233400Provided gasLimit is too low to complete the requested transaction.Provided gasLimit smaller than network estimation. Provide a higher gasLimit, and try again.
155234400Transaction can't have both feeLevel and fee parameters provided.Specify either feeLevel, or provide the detailed fee parameters for a transaction.
155235400EIP1559 chains need maxFee/priorityFee provided.EIP1559 chains need maxFee/priorityFee provided.
155236400Failed to parse the provided fee in request to decimals.Failed to parse the provided fee in request to decimals.
155237400PriorityFee cannot be larger than maxFee in creating transaction request.PriorityFee cannot be larger than maxFee in creating transaction requests.
155238400Non-EIP1559 chains need gasPrice provided.Non-EIP1559 chains need gasPrice provided.
155239400Invalid token address for transfer.Correct the token address, and try again.
155240400Invalid token standard for transfer.Correct the token standard, and try again.
155241400Invalid token decimal for transfer.Correct the token decimal, and try again.
155242400The lengths of amounts and nft tokens don't match.The lengths of amounts and NFT tokens don’t match.
155243400Missing bytecode for contract deployment.Provide bytecode for contract deployment, and try again.
155244400Cannot provide both WalletID and SourceAddress/Blockchain.Specify WalletID or provide the SourceAddress/Blockchain, and try the request again.
155245400Invalid amount in contract execution request.Invalid amount in contract execution request. Error raised when parsing amount in the request.
155247400Cannot provide both CallData and AbiFunctionSignature/AbiParameters.Specify CallData or provide AbiFunctionSignature/AbiParameters, and try the request again.
155264400Wait 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 codeHTTP codeError messageDescription
155501409Frozen wallets can not be updated or interact with, only query.Frozen wallets cannot be updated or interacted with. You can only query this wallet.
155502403Max amount of wallets (tentative 1M) reached under 1 wallet set.1M maximum amount of wallets has been reached under 1 wallet set.
155503400Metadata 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.
155504400Metadata 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.
155505400SCA 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.
155506400SCA wallet config is invalid.SCA wallet config is invalid.
155507400SCA 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.
155508400Can'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.
155509400Entity needs to setup paymaster policy on Mainnet before SCA account creation. Please check paymaster policy setupThe 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.
155510400The 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.
155511400Blockchain is not supported for wallet creation.The specified blockchain is not supported for wallet creation. See the list of supported blockchains.
155512404The 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.
155515400The 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 codeHTTP codeError messageDescription
155601400Failed 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 codeHTTP codeError messageDescription
155701N/AUser canceledThe user canceled or exited the execute UI.
155702N/A<Launch UI failed reason>Check the error message to see the exact UI launch failure reason.
155703N/AThe code you entered is not the same as the first oneThe code you entered is not the same as the first one.
155704N/AYour PIN can't have repeating or consecutive numbersYour PIN can’t have repeating or consecutive numbers. Try again with a valid PIN.
155705N/AYour hint can't be the same as the answerYour hint can’t be the same as the answer. Try again with a valid hint.
155706N/ANetwork errorNetwork error. Try again.
155707N/AFailed to encrypt dataFailed to encrypt data. Try again.
155708N/A"Biometrics instead of PIN" is disabledEnable the “Biometrics instead of PIN” SDK API.
155709N/AThe device system doesn't support biometricsCannot enable biometrics in this device. The user must use the PIN code.
155710N/AFailed to decrypt biometrics keyAsk the user to reset the biometrics settings.
155711N/AThe user has not enabled biometrics yetThe user skipped the biometrics setting.
155712N/AThe user refused to enable biometricsMust call the SetBiometricsPin SDK API so the user can enable biometrics.
155713N/AToo many requests. Try again laterWait for 30 minutes, and try again.
155714N/AToo many requests. The biometrics sensor on the device is lockedGo to the device system settings to unlock.
155715N/AThe user didn't enable biometricsThe 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.
155716N/AUnexpected error for biometricsUnexpected error. Try again.
155717N/AUser 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.
155718N/AUser token format is invalidUser token format is invalid. Ensure the format of the user token is correct, then perform login and execute the challenge again.
155719N/AUser 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.
155720N/ASocial login failedSocial login failed. The social provider returns failed during the execution of social login flow. Refer to the error message for more details.
155721N/ALogin info is missingLogin info is missing. Perform login and execute the challenge again.

Sign transaction errors

Error codeHTTP codeError messageDescription
155801400Transaction or rawTransaction is invalid.Invalid transaction or rawTransaction in request.
155802400Account not found.Cannot find account in the transaction header.
155803400Not signer account.Account is not the signer of this transaction.
155804400Transaction is already signed.Transaction is already signed.
155805400Transaction failed to deserialize.Transaction failed to de-serialize.
155806400The transaction size exceeds blockchain limit.The transaction size exceeds blockchain limit.
155807400The chain ID is not supported for signing.The typed data or transaction chain ID is not supported for EVM signing
155808400The chain ID is missing in sign request.The chain ID is missing from typed data or transaction for EVM signing.

Common errors

Error codeHTTP codeError messageDescription
156001404Cannot 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.
156002404Cannot 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.
156003404Cannot 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.
156004400Reusing 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.
156005404Cannot 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.
156006400TEST_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.
156007401TEST_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.
156008400Cannot 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.
156009400Fail to parse id as UUID in url.The specified id is invalid (must be in UUID format). Try again with a valid id.
156010404Cannot find the corresponding entity in the system.The specified entity does not exist, or is not configured. Try again with a valid entity.
156011404Cannot find target nftTokenId in the system.The nftTokenId does not exist. Try again with a valid nftTokenId.
156012404Cannot find corresponding pagination cursor in the system.The pagination parameters are invalid. Correct your pagination parameters, and try again.
156013400The provided entity secret is invalid.The specified entity secret is not valid. Create or re-encrypt your entity secret, and try again.
156014400Pagination 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.
156015409The secret for this entity has already been set.The secret for this entity has already been set.
156016403The 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.
156017400The specified blockchain parameters are incorrect.The blockchain parameters are invalid. Correct the blockchain parameters, and try again.
156018403The uploaded recovery file is invalid.The uploaded recovery file is invalid. Try again with a valid recovery file.
156019403Current 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.
156020403Please use a new idempotency key.Use a new idempotency key, and try again.
156021409A new wallet set ID is required.Use a new wallet set ID, and try again.
156023409EncodedByHex 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.
156024400Data 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.
156025400Invalid message in request.Sign message is invalid. Try the request again with a valid EIP-191 message.
156026400Invalid typed data in request.Typed data is invalid. Try the request again with a valid EIP-712 typed data.
156027400The 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.
156030400Invalid unsigned delegate action in request.Invalid unsigned delegate action in request.