Errors
This guide explains our approach to error responses and status codes.
HTTP Error Status Codes
We use the standard HTTP status codes found here. Any response with a status code of 400
or greater is considered an error.
Responses with a 4xx
status code are due to errors caused by the client. The client should fix the error before trying to send the request again.
Responses with a 5xx
status code are due to errors caused by our servers. For idempotent requests, the client can retry the request later, but should honor the Retry-After
response header if one is provided. For non-idempotent requests it is recommended not to perform an automatic retry.
Validation errors
We use the status code 400
for errors in syntax, and the status code 422
for semantic request errors.
Examples of 400
errors:
- Missing a
}
in the JSON request body. - Providing a
string
instead of anumber
in a request body.
Examples of 422
errors:
- Missing a required field in a request body.
- Providing a
number
that falls outside the valid range.
HTTP Error Response Body
All error response bodies have the following structure:
{
"errors": {
"foo": [
"must be an integer",
"must be greater than 0"
],
"bar": [
"must be a valid ID",
]
}
}
The errors
property
errors
propertyThe errors
property is an object with various sub-properties corresponding to the error you are receiving.
Properties within errors
errors
There will always be at least one property within errors
. All properties are string arrays.
Typically, the property names will match the names of request body properties, query parameters, headers, or other request components for which an error has been identified.
The property name general
is used for errors that don't correspond to a specific request component.
Updated almost 2 years ago