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.

​
Compliance Engine errors

This section includes the errors that can be returned from Compliance Engine API requests.

​
Standalone screening errors

Error codeHTTP codeError messageDescription
280001400Unsupported blockchainProvided blockchain either does not exist or is not supported.
280002400Invalid blockchain addressProvided blockchain address is not valid.