Circle APIs: Common Error Responses

HTTP status codes do not always provide sufficient information about the cause of an error. For more detailed programmatic handling of errors, responses contain additional JSON fields that describe the error.

General error format

Whenever an API request results in an error, the response will contain both a high-level error class specified by the status code and a human-readable within the body.

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

 "code": 2,
 "message": "Invalid entity.\n[<error-message1>...\n<error-messageN>]"

Extended error format

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

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

 "code": 2,
 "message": "Invalid entity.\nfield1 may not be null (was null)",
 "errors": [
     "error": "required",
     "message": "field1 may not be null (was null)",
     "location": "field1",
     "invalidValue": "null",
     "constraints": {} # see below for details

Extended error response contains a list of one or multiple error descriptions associated with it. Error description attributes should be read as follow:

errortype of an errorfalse
messagehuman-friendly messagefalse
locationperiod-separated path to the property that causes this error. An example could be field1 or address.billingCountryfalse
invalidValueactual value of the property specified in location key, as received by the servertrue
constraintsspecial object that contains additional details about the error and could be used for programmatic handling on the client sidetrue

Error types

There is a set of existing errors which can be handled by clients in an automatic way. Here is the list of error names with example messages and constraints, if applicable:

value_must_be_truefield1 must be true (was false)NA
value_must_be_falsefield1 must be false (was true)NA
requiredfield1 may not be null (was null)NA
not_requiredfield1 must be null (was foo)NA
min_valuefield1 must be greater than or equal to 2 (was 0)"constraints": { "min": 2 }
min_valuefield1 must be greater than 2.0 (was 2.0)"constraints": { "min": "2.0", "inclusive": false }
max_valuefield1 must be less than or equal to 99 (was 1024)"constraints": { "max": 99 }
max_valuefield1 be less than or equal to 99.99 (was 100)"constraints": { "max": "99.99", "inclusive": true }
length_outside_boundsfield1 must be between 2 and 5 (was qwerty)"constraints": { "min": 2, "max": 5 }
pattern_mismatchfield1 must match "[a-z]+" (was 123456)"constraints": { "pattern": "[a-z]+" }
date_not_in_pastfield1 must be in the past (was 2020-08-31T18:18:54.211Z)NA
date_not_in_futurefield1 must be in the future (was 2020-08-31T18:18:17.621Z)NA
number_formatfield1 numeric value out of bounds (<3 digits>.<2 digits> expected) (was 123.456)"constraints": { "max-integral-digits": 3, "max-fractional-digits": 2 }