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:
key | meaning | optional |
---|---|---|
error | type of an error | false |
message | human-friendly message | false |
location | period-separated path to the property that causes this error. An example could be field1 or address.billingCountry | false |
invalidValue | actual value of the property specified in location key, as received by the server | true |
constraints | special object that contains additional details about the error and could be used for programmatic handling on the client side | true |
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:
error | message | constraints |
---|---|---|
value_must_be_true | field1 must be true (was false) | NA |
value_must_be_false | field1 must be false (was true) | NA |
required | field1 may not be null (was null) | NA |
not_required | field1 must be null (was foo) | NA |
min_value | field1 must be greater than or equal to 2 (was 0) | "constraints": { "min": 2 } |
min_value | field1 must be greater than 2.0 (was 2.0) | "constraints": { "min": "2.0", "inclusive": false } |
max_value | field1 must be less than or equal to 99 (was 1024) | "constraints": { "max": 99 } |
max_value | field1 be less than or equal to 99.99 (was 100) | "constraints": { "max": "99.99", "inclusive": true } |
length_outside_bounds | field1 must be between 2 and 5 (was qwerty) | "constraints": { "min": 2, "max": 5 } |
pattern_mismatch | field1 must match "[a-z]+" (was 123456) | "constraints": { "pattern": "[a-z]+" } |
date_not_in_past | field1 must be in the past (was 2020-08-31T18:18:54.211Z) | NA |
date_not_in_future | field1 must be in the future (was 2020-08-31T18:18:17.621Z) | NA |
number_format | field1 numeric value out of bounds (<3 digits>.<2 digits> expected) (was 123.456) | "constraints": { "max-integral-digits": 3, "max-fractional-digits": 2 } |
Updated 3 months ago