HTTP Errors

Learn about error format and common errors encountered using the Circle platform.

The Circle platform returns an HTTP status code when it detects an error in an API request.

General error format

HTTP status codes do not always provide sufficient information to determine the cause of the error, but the responses to a request typically contain additional JSON fields that provide additional details. For example, if a request contains an invalid parameter, the response includes the following:

HTTP/1.1 400 Bad RequestContent-Type: application/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 resembles the following:

HTTP/1.1 400 Bad RequestContent-Type: application/json

{
  "code": 2,
  "message": "API parameter invalid",
  "errors": [
    {
      "error": "required",
      "message": "fail to bind request to CreateWalletSetRequest: EOF",
      "location": "field1",
      "invalidValue": "null",
      "constraints": { }
    }
  ]
}

Common Web3 Services error messages

This section describes some common extended error messages you might encounter using Web3 Services APIs.

General

The following errors result from malformed request.

Error CodeHTTP codeError MessageDescription
-1400Something went wrongAn unknown error occurred while processing the API request, likely an invalid parameter or API key.
3403ForbiddenThe API key used does not have access to the requested endpoint. 

400 Bad Request

A 400 HTTP status code typically results when the request includes an invalid parameter. The following table includes additional error messages associated with error code 2.

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 tag"If 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 parameter is not in the correct format.
2400INVALID: parameter emptyThe parameter is required for this request. Try the request again with this parameter.

Programmable wallet error messages

This section describes the errors that can be returned for Programmable Wallet API requests.

User error codes (155101 - 155199)

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. Please generate a new user token and try the request again.
155105403The userToken is invalid.The user token is not invalid. Please generate a new user token and try the request again.
155106409The user had already been initialized.The user has already been initialized. Please 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. Please 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, please 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, please 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. Please 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. Please wait for cold time 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. Please 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.

Transaction error codes (155201 - 155299)

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. Please 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 on-chain 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. Please 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. Please 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. Please 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).Please 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.Please 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.Please 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.Please provide ABI signature, and try again.
155231400Transaction needs feeLevel or gasLimit provided.Please provide feeLevel or gasLimit, and try again.
155232400SCA transaction needs feeLevel provided.SCA transaction needs feeLevel provided. Please specify the feeLevel, and try again.
155233400Provided gasLimit is too low to complete the requested transaction.Provided gasLimit smaller than network estimation. Please 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 params 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.Please correct the token address, and try again.
155240400Invalid token standard for transfer.Please correct the token standard, and try again.
155241400Invalid token decimal for transfer.Please 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.Please 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.

Wallet error codes (155501 - 155599)

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. Please 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 is not eligible for 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.

Wallet Set error codes (155601 - 155699)

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 error codes (155701 - 155799)

Error codeHTTP CodeError MessageDescription
155701N/AUser canceledThe user canceled or exited the execute UI.
155702N/A<Launch UI failed reason>Please check the error message to see the exact UI launch failure reason.
155703N/AThe code you entered is not the same as the first one.The code you entered is not the same as the first one.
155704N/AYour PIN can’t have repeating or consecutive numbers.Your PIN can’t have repeating or consecutive numbers. Try again with a valid PIN.
155705N/AYour 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.
155706N/ANetwork errorNetwork error. Try again.
155707N/AFailed to encrypt dataFailed to encrypt data. Try again.
155708N/A"Biometrics instead of PIN" is disabledPlease enable 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 laterPlease wait for 30 minutes, and try again.
155714N/AToo many requests. The biometrics sensor on the device is locked.Please go 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.

Common error codes (156001 - 156099)

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. Please 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. Please correct your pagination parameters, and try again.
156013400The provided entity secret is invalid.The specified entity secret is not valid. Please 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. Please provide encrypted ciphertext in the Developer console.
156017400The specified blockchain parameters are incorrect.The blockchain parameters are invalid. Please 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. Please rotate the entity secret first in the Developer console, and try again.
156020403Please use a new idempotency key.Please use a new idempotency key, and try again.
156021409A new wallet set ID is required.Please 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. Please 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. Please 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.Please try again with a supported blockchain. Please see the guide Supported Blockchains and Currencies for the complete list of supported blockchains.

Smart Contract Platform error messages

This section includes the errors that can be returned from Smart Contract Platform API requests.

Contract error codes (175001 - 175200)

Error CodeHTTP CodeError MessageDescription
175001404Contract not found.The specified contract does not exist in the system.
175002400No ABI JSON for the target contract.Cannot execute a read function on a contract without the ABI JSON.
175003400Constructor parameters length must match constructor signature.The number of constructor parameters must match the constructor signature.
175004409Contract already exists.The contract already exists in the system.
175005400Address is not a contract address.The given address is not associated with a smart contract.
175006400Contract is archived.Attempted to interact with an archived contract.
175007400Invalid ABI JSON.The inputted ABI JSON is not correctly formatted.
175008400Multi-layered proxies are not supported.Importing a multi-layered proxy contract is not currently supported.
175009400Contract deployment pending.Contract deployment must be completed before function execution is available.
175010400ABI function not found.The ABI function was not found on the contract.
175011400Empty update on a contract.An empty update for a contract is not allowed

Template error codes (175201 - 175400)

Error CodeHTTP CodeError MessageDescription
175201404Template not found.The specified template does not exist in the system.
175202400Deploying this template is temporarily disabled.Deploying this template is temporarily disabled.
175203400Invalid template deployment parameter.The request contains an invalid field in the template parameters.
175204400Missing required template deployment parameter.The request is missing a required field in the template parameters.

Common error codes (175401 - 175600)

CodeHTTP CodeError MessageDescription
175401400Fail to parse id as UUID in url.The specified ID is invalid (must be in UUID format). Try again with a valid ID.
175402400The specified blockchain is either not supported or deprecated.The specified blockchain is either not supported or deprecated.
175403409Please use a new idempotency key.Please use a new idempotency key and try again.
175404400TEST_API key cannot be used with blockchain mainnets, or LIVE_API key cannot be used with blockchain testnets.TEST_API key cannot be used with blockchain mainnets, or LIVE_API key cannot be used with blockchain testnets.
175405401TEST_API key or LIVE_API key is not found for the request.TEST_API key or LIVE_API key is not found for the request.
175406400This feature is temporarily disabled.This feature is temporarily disabled.
175407400The specified blockchain is currently unavailable.The specified blockchain is currently unavailable. Please check the Circle Status page for more details.

Transaction error codes (177001 - 177607)

CodeHTTP CodeError MessageDescription
177001400transaction nonce is inconsistent with sender's latest nonceThe transaction nonce is inconsistent with the sender's latest nonce.
177002400user op nonce can not be larger than 0 when smart contract wallet hasn't been deployedUser op nonce can not be larger than 0 when the smart contract wallet hasn't been deployed.
177003400failed to execute this request on EVM due to insufficient token when estimating feeFailed to execute this request on EVM due to insufficient tokens when estimating the fee.
177004400the total cost of executing transaction is higher than the balance of the user's account when estimating feeWhen estimating the fee, the total cost of executing the transaction is higher than the balance of the user's account.
177005400the sender address is not token owner or approved when estimating token transferThe sender address is not token owner or approved when estimating token transfer.
177006400gas required exceeds allowance when estimating feeGas required exceeds allowance when estimating fee.
177007400estimate fee execution revertedEstimate fee execution reverted.
177008400ABI function signature can’t pack ABI parameterABI function signature can’t pack ABI parameter.
177009400fails to perform transaction estimationFails to perform transaction estimation.
177010400maxFee * gasLimit exceed configurable max transaction fee (default is 1 native token)The MaxFee * GasLimit exceeds the configurable max transaction fee (default is 1 native token).
177011400transaction needs feeLevel or gasLimit providedThe transaction requires feeLevel or gasLimit to be provided in the request.
177012400sca transaction needs feeLevel providedThe SCA transaction requires feeLevel to be provided in the request.
177013400EIP1559 chains need maxFee/priorityFee providedEIP1559 chains require maxFee and priorityFee to be provided in the request.
177014400priorityFee cannot be larger than maxFee in creating transaction requestCreating transaction requestspriorityFee cannot be larger than maxFee.
177015400missing bytecode for contract deploymentMissing bytecode for contract deployment.
177016400cannot provide both WalletID and SourceAddress/BlockchainYou cannot provide WalletID and SourceAddress/Blockchain in a request.
177017400Invalid amount in contract execution requestThe amount in the contract execution request is invalid.
177018400policy is not activated and cannot be usedThe Gas Station paymaster policy is not activated and cannot be used.
177019400exceeded max daily transaction of the policyThe Gas Station paymaster policy maximum daily transaction limit has been reached.
177020400exceeded max spend USD per transaction of the policyThe transaction cost exceeds the Gas Station paymaster policy maximum spend per transaction in USD.
177021400exceeded max spend USD daily of the policyThe Gas Station paymaster policy for maximum spending daily in USD has been reached.
177022400exceeded max native token daily of the policyThe Gas Station paymaster policy for maximum native tokens daily of the policy.
177023400sender is in policy blocklistThe sender is on the Gas Station paymaster policy blocklist.
177024400wallet and request's blockchain mismatch.The wallet and blockchain in the request should be the same.
177301400wallet is FrozenFrozen wallets can not be updated or interacted with; they can only be queried.
177302400invalid sca wallet configThe SCA wallet configuration is invalid.
177303400sca wallet first-time transaction is still in progressThe SCA wallet needs to wait for the first-time transaction to finish deploying the wallet before processing more transactions.
177304400SCA account is not supported on the given blockchainThe SCA account is not supported on the given blockchain.
177305400Entity is not eligible for SCA account creation. Please check paymaster policy setupThe entity is not eligible for SCA account creation. Please check the Gas Station paymaster policy setup.
177601400could be caused by either no such wallet or wallet is not accessible to the callerThe target wallet cannot be found in the system. Either the specified wallet doesn't exist, or it's inaccessible to the caller.
177602400reusing an entity secret ciphertext is not allowed. Please re-encrypt the entity secret to generate new ciphertextReusing an entity's secret ciphertext is not allowed. Please re-encrypt the entity secret to generate a new ciphertext.
177603400entity is likely not properly set up during the onboarding processThe corresponding entity cannot be found in the system.
177604400the provided entity secret is invalidThe provided entity secret is invalid.
177605400the entity secret has not been set yet. Please provide encrypted ciphertext in the consoleThe entity secret has not been set up on your account. Please provide encrypted ciphertext in the console.
177606400current entity secret is invalid. Please rotate the entity secret firstThe provided entity secret is invalid. Please rotate the entity secret first and send another API request.
177607400please use a new idempotency keyPlease use a new idempotency key.