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 }


Did this page help you?