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.

​
Contracts errors

This section includes the errors that can be returned from the Circle Contracts API requests.

​
Contract errors

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 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
175012400Unable to query contract.Unable to query contract. Check your parameters and try again.
175013400ABI function is not supported.The ABI function of the contract is not supported.

​
Template errors

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.
175205400Estimation is not supported.Estimating the deployment of this template is not supported.

​
Event subscription errors

Error codeHTTP codeError messageDescription
175301404Event subscription not found.The specified event subscription does not exist or is not accessible to the caller.
175302409Event subscription already exist.The specified event has already been created for this contract.
175303400The specified event signature does not exist.The specified event signature does not exist on this contract.

​
Common errors

Error 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.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 unavailable.The specified blockchain is unavailable. Check the Circle Status page for more details.
175408404Cannot find corresponding pagination cursor in the system.Cannot find corresponding pagination cursor in the system.
175409403Entities with restrictions cannot perform this operation.Entities with restrictions cannot perform this operation.
175410400invalid address formatThe address format is invalid.

​
Transaction errors

Error 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. 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. 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. Provide encrypted ciphertext in the console.
177606400current entity secret is invalid. Please rotate the entity secret firstThe provided entity secret is invalid. Rotate the entity secret first and send another API request.
177607400please use a new idempotency keyUse a new idempotency key.
177901400smart contract query failedError when querying contract. Check parameters and try again.