HTTP Errors

In cases where an API request is made and the error can be detected immediately, an applicable HTTP status code is returned. 

General Error Format

HTTP status codes do not always provide sufficient information about the cause of an error. Responses contain additional JSON fields describing the error for more detailed programmatic handling of errors.

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

  "code": 2,
  "message": "API parameter invalid"

Extended Format

In some cases, extended information is available for clients about why a request has failed. For example, failing to supply a value for a required field will result in the following error:

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": { }

Circle’s Extended Error Messages

Below are some common extended error messages you may encounter as you implement Circle’s Programmable Wallets API.

Error CodeMessageDescription
-1Something went wrongAn unknown error occurred processing the API request, likely an invalid parameter or API key.
2Invalid EntityThere is an error in the JSON format passed in the request.
2Fail to get activity from path: invalid UUID lengthThe activity must be in UUID format. 
2Fail to bind request to parameter: invalid UUID formatThe parameter must be in UUID format. 
2fail to bind request to activity: invalid characterThe activity contains an invalid character. Try again without the character.
2Error: Field validationOne of the fields in the request is invalid. 
2Error: Field validation for 'blockchain' failed on the 'blockchain' tagThe blockchain does not exist. Try again with a supported blockchain
2Error: 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.
2Error: Field validation for parameter failed on the min tagThe parameter is not in the correct format. 
2Cannot unmarshallThe parameter is not in the correct format
2The blockchain in request does not match the blockchain of wallet.The blockchain selected for the request does not match the source wallet’s blockchain. 
2INVALID: parameter emptyThe parameter is required for this request. Try the request again with this parameter. 
3ForbiddenThe API key used does not have access to the requested endpoint. 
155105User token is invalid in the system.The userToken does not exist. Try again with a new userToken. 
155105User token was expiredThe userToken has expired and must be re-generated.