API errors - Circle Docs

Circle APIs return an HTTP status code when they encounter an error:

4xx errors are client errors. They communicate a mistake in the request and, where possible, suggest a fix.
5xx errors are unexpected server-side errors.

Product-specific error codes are documented on each product’s error codes page. See Wallets, Contracts, Mint, and CPN.

General error format

HTTP status codes do not always provide sufficient information to determine the cause of the error. The response body 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 Request
Content-Type: application/json

Body

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

Extended error format

For validation failures, the response includes an errors array with per-field detail. For example, if a request is missing a required field: Header

HTTP/1.1 400 Bad Request
Content-Type: application/json

Body

{
  "code": 2,
  "message": "API parameter invalid",
  "errors": [
    {
      "error": "required",
      "message": "fail to bind request to CreateWalletSetRequest: EOF",
      "location": "field1",
      "invalidValue": "null",
      "constraints": {}
    }
  ]
}

General errors

The following errors can be returned for any request.

Error code	HTTP code	Error message	Resolution
`-1`	`400`	`Something went wrong`	An unknown error occurred. Retry with exponential backoff.
`3`	`403`	`Forbidden`	The API key does not have access to the requested endpoint.
`2`	`400`	`API parameter invalid`	The request body or a parameter value is invalid. Read the `message` field for specifics.

​General error format

​Extended error format

​General errors

General error format

Extended error format

General errors