Wallets API error codes

For error response shapes and general errors that can be returned by any Circle API, see API errors. For error codes surfaced by the user-controlled wallet SDK’s built-in UI (155701–155721), see SDK error codes.

User (`155101`–`155146`)

Error code	HTTP code	Error message	Resolution
`155101`	`409`	`Existing user already created with the provided userId.`	Retry with a unique user ID.
`155102`	`404`	`Cannot find the user id in the system.`	Verify the user ID and confirm your entity has access to it.
`155103`	`401`	`Cannot find the user token in the system.`	Generate a new user token.
`155104`	`403`	`The userToken had expired.`	Generate a new user token.
`155105`	`403`	`The userToken is invalid.`	Generate a new user token.
`155106`	`409`	`The user had already been initialized.`	Query the user status to check whether 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.`	Reset the PIN with `PUT /user/pin`.
`155108`	`409`	`User has previously set up their security questions, and they can't be reset.`	Security questions can only be set once and cannot be reset.
`155109`	`409`	`The specified user has been disabled.`	Re-enable the user.
`155110`	`400`	`User has not set up a PIN yet.`	Initialize the user or set a PIN before retrying.
`155111`	`400`	`User hasn't set the security questions for PIN backup yet.`	Initialize the user or set security questions before retrying.
`155112`	`400`	`The user has inputted the incorrect pin.`	Retry with the correct PIN.
`155113`	`400`	`Provided device ID is not found in the system.`	Verify the device ID.
`155114`	`400`	`Provided app ID is not recognized in the system.`	Verify the app ID. Find it in the Circle Console or via `GET /config/entity`.
`155115`	`400`	`The user has inputted the incorrect security answers`	Retry with the correct security answers.
`155116`	`404`	`The challenge ID doesn't exist in the system.`	Verify the challenge ID.
`155117`	`400`	`The content provided for approval is not correct.`	Update to the latest SDK version.
`155118`	`400`	`Encryption key does not match with the user's token. Call POST /users/token to get the correct token encryption key pair.`	Call `POST /users/token` to get a matching token and encryption keypair.
`155119`	`400`	`The user's PIN input is locked. It will be unlocked after the cooldown period.`	Wait for the cooldown to end, then retry.
`155120`	`400`	`The user's security questions input is locked. It will be unlocked after the cooldown period.`	Wait for the cooldown to end, then retry.
`155121`	`403`	`The provided challengeId has expired.`	Create a new challenge.
`155122`	`403`	`The provided challengeId is invalid`	Create a new challenge.
`155123`	`403`	`No extra information provided when adding PIN-related requests.`	Update to the latest SDK version. The challenge approval payload is malformed.
`155124`	`403`	`The extra information provided for PIN-related requests is invalid.`	Update to the latest SDK version. The challenge approval payload is malformed.
`155130`	`400`	`User OTP token is expired.`	Request a new OTP email.
`155131`	`400`	`User OTP token is invalid.`	Verify the OTP token in the request.
`155132`	`404`	`User OTP value is not found.`	Request an OTP email first.
`155133`	`400`	`User OTP value is invalid.`	Verify the OTP value in the request.
`155134`	`400`	`User OTP value is not matched.`	Confirm the OTP value matches the OTP token.
`155135`	`400`	`User's email is invalid.`	Verify the email format.
`155136`	`400`	`User's email is not matched.`	Confirm the email matches the user’s registered email.
`155137`	`400`	`User's device ID is invalid.`	Verify the device ID in the request.
`155138`	`400`	`Failed to send the email.`	Check the SMTP configuration in the Circle Console.
`155139`	`400`	`The idToken / accessToken of SSO is expired.`	Refresh the SSO token from your SSO provider.
`155140`	`400`	`Failed to validate the idToken/ accessToken.`	Verify the SSO provider configuration in the Circle Console.
`155141`	`400`	`The user has exceeded the max limit (5) of entering OTP at the moment.`	Wait 60 minutes before retrying.
`155142`	`400`	`The max limit (5) of sending OTP has been exceeded at the moment.`	Wait 60 minutes before retrying.
`155143`	`400`	`The device token is expired.`	Request a new device token. Tokens expire after 10 minutes.
`155144`	`400`	`The device token is invalid.`	Request a new device token. Only one active token is allowed per `deviceId`.
`155145`	`404`	`The device token is not found.`	Request a new device token.
`155146`	`400`	`The OTP token is invalid as the user has entered it incorrectly three times.`	Request a new OTP email.

Authentication configuration (`155150`–`155157`)

Error code	HTTP code	Error message	Resolution
`155150`	`404`	`The SMTP server configuration is not found.`	Complete the SMTP configuration in the Circle Console.
`155151`	`400`	`The SMTP server configuration is invalid.`	Fix the SMTP configuration in the Circle Console.
`155152`	`404`	`The SSO provider configuration is not found.`	Add an SSO provider in the Circle Console.
`155154`	`400`	`The OTP email template is invalid.`	Fix the OTP email template configuration.
`155155`	`404`	`The OTP email template is not found.`	Add an OTP email template in the Circle Console.
`155156`	`400`	`Failed to update the email template.`	Check the OTP email template content.
`155157`	`400`	`Failed to update the SMTP server`	Check the SMTP configuration in the Circle Console.

Transaction (`155201`–`155264`)

Error code	HTTP code	Error message	Resolution
`155201`	`400`	`Not enough funds to fulfill the withdraw request.`	Add native tokens to the wallet to cover pending transactions.
`155202`	`400`	`Transaction nonce is inconsistent with sender's latest nonce.`	Retry the transaction after the previous one reaches finality.
`155203`	`400`	`User op nonce can not be larger than 0 when smart contract wallet hasn't been deployed.`	Send the first user op with nonce 0 to trigger contract deployment.
`155204`	`400`	`The total cost of executing transaction is higher than the balance of the user's account when estimating fee.`	Add native tokens to cover the total transaction cost.
`155205`	`400`	`Failed to execute this request on EVM due to insufficient token when estimating fee.`	Add the required non-native token balance to the wallet.
`155206`	`400`	`The sender address is not token owner or approved when estimating token transfer.`	Approve the caller to spend the token, or use the token owner as sender.
`155207`	`400`	`Gas required exceeds allowance when estimating fee.`	Increase the gas allowance.
`155208`	`400`	`Estimate fee execution reverted.`	The transaction reverted onchain during fee estimation. Verify the target contract, function, and parameters.
`155209`	`400`	`ABI function signature can't pack ABI parameter.`	Correct the ABI parameters.
`155210`	`400`	`Fails to perform transaction estimation.`	Retry the request. If the error persists, verify the request parameters against the target blockchain.
`155211`	`400`	`MaxFee * GasLimit exceed configurable max transaction fee (default is 1 native token).`	Reduce `maxFee` or `gasLimit`. Circle applies a per-blockchain maximum fee limit, which defaults to 1 unit of the blockchain’s native token.
`155215`	`400`	`Unsupported operation for transaction.`	Check the transaction status. The requested operation is not valid in its current state.
`155218`	`400`	`Invalid number of nft in transaction request.`	Provide multiple tokens only for ERC-1155 transfers.
`155219`	`400`	`Invalid destination address.`	Provide a valid destination address.
`155220`	`400`	`Wallet and token's blockchain mismatch.`	Use a wallet and token on the same blockchain.
`155221`	`400`	`Invalid amounts in transfer request.`	For token standards other than ERC-1155, provide a single amount in the transfer request.
`155222`	`404`	`NFT metadata can not be found.`	Confirm that the token contract exposes NFT metadata.
`155223`	`400`	`Unsupported userId for get transactions.`	Remove `userId` from the query parameters.
`155224`	`400`	`Failed to parse the provided amounts in request to decimals.`	Provide amounts as valid decimal numbers.
`155225`	`400`	`Wallet and request's blockchain mismatch.`	Use a wallet and request blockchain that match.
`155226`	`400`	`Invalid source address.`	Provide a valid source address.
`155227`	`400`	`Invalid transaction type.`	Provide an outbound transaction.
`155228`	`400`	`Missing token ID.`	Include the token ID in the request.
`155229`	`400`	`Transaction is not eligible for operation.`	Check the transaction status. The operation is no longer allowed in its current state.
`155230`	`400`	`No call data or abi signature provided.`	Provide `callData` or an ABI signature.
`155231`	`400`	`Transaction needs feeLevel or gasLimit provided.`	Provide `feeLevel` or `gasLimit`.
`155232`	`400`	`SCA transaction needs feeLevel provided.`	Provide `feeLevel` for SCA transactions.
`155233`	`400`	`Provided gasLimit is too low to complete the requested transaction.`	Provide a higher `gasLimit` than the network estimate.
`155234`	`400`	`Transaction can't have both feeLevel and fee parameters provided.`	Provide either `feeLevel` or the detailed fee parameters, not both.
`155235`	`400`	`EIP1559 chains need maxFee/priorityFee provided.`	Provide `maxFee` and `priorityFee` for EIP-1559 blockchains.
`155236`	`400`	`Failed to parse the provided fee in request to decimals.`	Provide fee values as valid decimal numbers.
`155237`	`400`	`PriorityFee cannot be larger than maxFee in creating transaction request.`	Set `priorityFee` less than or equal to `maxFee`.
`155238`	`400`	`Non-EIP1559 chains need gasPrice provided.`	Provide `gasPrice` for non-EIP-1559 blockchains.
`155239`	`400`	`Invalid token address for transfer.`	Provide a valid token address.
`155240`	`400`	`Invalid token standard for transfer.`	Provide a supported token standard.
`155241`	`400`	`Invalid token decimal for transfer.`	Provide a valid token decimal.
`155242`	`400`	`The lengths of amounts and nft tokens don't match.`	Ensure the amounts and NFT token arrays have the same length.
`155243`	`400`	`Missing bytecode for contract deployment.`	Provide `bytecode` for the contract deployment.
`155244`	`400`	`Cannot provide both WalletID and SourceAddress/Blockchain.`	Provide either `walletId` or `sourceAddress` and `blockchain`, not both.
`155245`	`400`	`Invalid amount in contract execution request.`	Provide the amount in the contract execution request as a valid number.
`155247`	`400`	`Cannot provide both CallData and AbiFunctionSignature/AbiParameters.`	Provide either `callData` or `abiFunctionSignature` and `abiParameters`, not both.
`155248`	`400`	`Policy is not activated and cannot be used.`	Activate the Gas Station policy before submitting transactions.
`155249`	`400`	`Exceeded max daily transaction of the policy.`	Wait for the daily counter to reset, or raise the policy’s max daily transaction limit.
`155250`	`400`	`Exceeded max spend USD per transaction of the policy.`	Reduce the transaction amount, or raise the policy’s per-transaction USD limit.
`155251`	`400`	`Exceeded max spend USD daily of the policy.`	Wait for the daily counter to reset, or raise the policy’s daily USD spend limit.
`155252`	`400`	`Exceeded max native token daily of the policy.`	Wait for the daily counter to reset, or raise the policy’s daily native token limit.
`155253`	`400`	`Sender is in policy blocklist.`	Remove the sender from the policy’s blocklist, or use a wallet not on the blocklist.
`155254`	`400`	`Non-EIP1559 chains don't support maxFee/priorityFee.`	Remove `maxFee` and `priorityFee`. Use `gasPrice` for non-EIP-1559 blockchains.
`155255`	`400`	`The entity is restricted in paymaster.`	Check the account’s Gas Station policy configuration.
`155256`	`400`	`Default policy for the blockchain is not found in paymaster.`	Configure a default Gas Station policy for the blockchain.
`155257`	`400`	`The transfer amount is insufficient to make the destination account rent exempted or the balance of the source account is insufficient to remain rent exempted. The source address's remaining balance after transfer must be either zero or at least the rent exemption threshold.`	On Solana, adjust the transfer so the destination reaches the rent exemption threshold and the source balance is either zero or at least the threshold.
`155258`	`400`	`The asset amount owned by the wallet is insufficient for the transaction.`	Confirm that the wallet’s onchain balance can cover the transaction. Add funds or wait for the balance to update, then retry.
`155259`	`400`	`The token address in the destination associated token account does not match the token address in the transaction.`	Use a destination associated token account whose token address matches the transaction’s token address.
`155260`	`400`	`The account is not valid for the instruction.`	Verify that every account is valid for the Solana instruction.
`155261`	`400`	`The seeds provided for creating associated token account are invalid.`	Verify the associated token account inputs and retry with valid seeds.
`155262`	`400`	`The account is not found, could be caused by transacting from a new account with zero balance.`	Fund the account and retry. On Solana, an account with zero balance may not exist onchain.
`155263`	`400`	`The transaction size is too large, could be caused by too many parameters.`	Reduce the number or size of transaction parameters, or split the operation into multiple transactions.
`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 for pending transactions to finalize. To increase throughput, distribute transactions across multiple wallets. See Transaction throughput.

Wallet (`155501`–`155515`)

Error code	HTTP code	Error message	Resolution
`155501`	`409`	`Frozen wallets can not be updated or interact with, only query.`	Frozen wallets support query only.
`155502`	`403`	`Max amount of wallets (tentative 1M) reached under 1 wallet set.`	Create a new wallet set to add more wallets.
`155503`	`400`	`Metadata array length needs to match wallet count in create developer wallets request.`	Match the `metadata` array length to the wallet count in `POST /developer/wallets`.
`155504`	`400`	`Metadata array length needs to match number of blockchains in create user wallets request.`	Match the `metadata` array length to 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.`	Wait for the first SCA transaction to be queued before submitting more.
`155506`	`400`	`SCA wallet config is invalid.`	Check the SCA wallet configuration.
`155507`	`400`	`SCA account is not supported on the given blockchain.`	Use a supported blockchain. See supported blockchains.
`155509`	`400`	`Entity needs to setup paymaster policy on Mainnet before SCA account creation. Please check paymaster policy setup`	Configure a single paymaster policy for the blockchain in the Circle Console.
`155510`	`400`	`The operation is not supported on the blockchain you specify.`	Use a wallet on a blockchain that supports this operation.
`155511`	`400`	`Blockchain is not supported for wallet creation.`	Use a supported blockchain. See supported blockchains.
`155512`	`404`	`The owner of the SCA wallet can not be found.`	Check whether ownership was transferred or the account is set up correctly.
`155515`	`400`	`The provided wallet account type is not supported by this API.`	Use a supported account type. See account types.

Wallet set (`155601`)

Error code	HTTP code	Error message	Resolution
`155601`	`400`	`Failed to retrieve wallet set which already exists.`	Retry with a unique wallet set ID.

Transaction signing (`155801`–`155808`)

Error code	HTTP code	Error message	Resolution
`155801`	`400`	`Transaction or rawTransaction is invalid.`	Provide a valid `transaction` or `rawTransaction`.
`155802`	`400`	`Account not found.`	Verify the account in the transaction header.
`155803`	`400`	`Not signer account.`	Sign from the account that is the transaction’s signer.
`155804`	`400`	`Transaction is already signed.`	No action required.
`155805`	`400`	`Transaction failed to deserialize.`	Check the transaction format.
`155806`	`400`	`The transaction size exceeds blockchain limit.`	Reduce the transaction payload.
`155807`	`400`	`The chain ID is not supported for signing.`	Use a supported chain ID for EVM signing.
`155808`	`400`	`The chain ID is missing in sign request.`	Include a chain ID in the typed data or transaction.

Shared (`156001`–`156030`)

Error code	HTTP code	Error message	Resolution
`156001`	`404`	`Cannot find target wallet in the system. Either the specified wallet doesn't exist or it's not accessible to the caller.`	Verify the 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.`	Verify the 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.`	Verify the transaction ID.
`156004`	`400`	`Reusing an entity secret ciphertext is not allowed. Please re-encrypt the entity secret to generate new ciphertext.`	Re-encrypt the entity secret to generate a new ciphertext.
`156005`	`404`	`Cannot find target wallet set in the system. Either no such wallet set, or it's not accessible to the caller.`	Verify the wallet set ID.
`156006`	`400`	`TEST_API key cannot be used with blockchain mainnets, or LIVE_API key cannot be used with blockchain testnets.`	Use a `TEST_API` key for testnets and a `LIVE_API` key for mainnets.
`156007`	`401`	`TEST_API key or LIVE_API key is not found for the request.`	Provide 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.`	Verify the entity config.
`156009`	`400`	`Fail to parse id as UUID in url.`	Provide an ID in UUID format.
`156010`	`404`	`Cannot find the corresponding entity in the system.`	Verify the entity.
`156011`	`404`	`Cannot find target nftTokenId in the system.`	Verify the `nftTokenId`.
`156012`	`404`	`Cannot find corresponding pagination cursor in the system.`	Correct the pagination parameters.
`156013`	`400`	`The provided entity secret is invalid.`	Create or re-encrypt the entity secret.
`156014`	`400`	`Pagination params are invalid. Only UUID format is supported for pageBefore and pageAfter.`	Use UUID format for `pageBefore` and `pageAfter`.
`156015`	`409`	`The secret for this entity has already been set.`	No action required.
`156016`	`403`	`The entity secret has not been set yet. Please provide encrypted ciphertext in the console.`	Provide encrypted ciphertext in the Circle Console.
`156017`	`400`	`The specified blockchain parameters are incorrect.`	Correct the blockchain parameters.
`156018`	`403`	`The uploaded recovery file is invalid.`	Upload a valid recovery file.
`156019`	`403`	`Current entity secret is invalid. Please rotate the entity secret first.`	Rotate the entity secret in the Circle Console.
`156020`	`403`	`Please use a new idempotency key.`	Use a new idempotency key.
`156021`	`409`	`A new wallet set ID is required.`	Use a new wallet set ID.
`156023`	`409`	`EncodedByHex is true in sign request, but the message is not hex encoded.`	Provide a hex-encoded message, or set `encodedByHex` to `false`.
`156024`	`400`	`Data is not a valid JSON string in sign request.`	Provide a valid JSON typed data string.
`156025`	`400`	`Invalid message in request.`	Provide a valid EIP-191 message.
`156026`	`400`	`Invalid typed data in request.`	Provide valid EIP-712 typed data.
`156027`	`400`	`The specified blockchain is either not supported or deprecated.`	Use a supported blockchain. See supported blockchains.
`156030`	`400`	`Invalid unsigned delegate action in request.`	Provide a valid delegate action.

Compliance Engine screening (`280001`–`280002`)

Error code	HTTP code	Error message	Resolution
`280001`	`400`	`Unsupported blockchain`	Use a supported blockchain.
`280002`	`400`	`Invalid blockchain address`	Provide a valid blockchain address.

API overview

Configurations

Developer-controlled

User-controlled

Modular

Compliance Engine

Wallets API error codes

User (`155101`–`155146`)

Authentication configuration (`155150`–`155157`)

Transaction (`155201`–`155264`)

Wallet (`155501`–`155515`)

Wallet set (`155601`)

Transaction signing (`155801`–`155808`)

Shared (`156001`–`156030`)

Compliance Engine screening (`280001`–`280002`)

​User (155101–155146)

​Authentication configuration (155150–155157)

​Transaction (155201–155264)

​Wallet (155501–155515)

​Wallet set (155601)

​Transaction signing (155801–155808)

​Shared (156001–156030)

​Compliance Engine screening (280001–280002)

User (`155101`–`155146`)

Authentication configuration (`155150`–`155157`)

Transaction (`155201`–`155264`)

Wallet (`155501`–`155515`)

Wallet set (`155601`)

Transaction signing (`155801`–`155808`)

Shared (`156001`–`156030`)

Compliance Engine screening (`280001`–`280002`)