Wallets API error codes

Descriptions of error codes returned by the Wallets and Compliance Engine APIs.

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.
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 limits and optimizations.

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.