Error responses¶
API description¶
Every response is JSON.
If the HTTP status is not OK (<200 or >=400), the response contains a JSON mapping, with the following attributes:
code
: matches the HTTP status code (e.g400
)errno
: stable application-level error number (e.g.109
)error
: string description of error type (e.g."Bad request"
)message
: context information (e.g."Invalid request parameters"
)info
: online resource (e.g. URL to error details)details
: additional details (e.g. list of validation errors)
Example response
{
"code": 412,
"errno": 114,
"error": "Precondition Failed",
"message": "Resource was modified meanwhile",
"info": "https://server/docs/api.html#errors",
}
Refer yourself to the set of errors codes.
Retry-After indicators¶
A Retry-After
header will be added to error responses (>=500),
telling the client how many seconds it should wait before trying
again.
Retry-After: 30
Precondition errors¶
As detailed in the timestamps section, it is
possible to add concurrency control using ETag
request headers.
When a the provided preconditions are not met, a 412 Precondition Failed
error response
is returned.
Additional information about the record currently stored on the server will be
provided in the details
field:
{
"code": 412,
"errno": 114,
"error":"Precondition Failed"
"message": "Resource was modified meanwhile",
"details": {
"existing": {
"last_modified": 1436434441550,
"id": "00dd028f-16f7-4755-ab0d-e0dc0cb5da92",
"title": "Original title"
}
},
}
Validation errors¶
When multiple validation errors occur on a request, the first one is presented in the message.
The full list of validation errors is provided in the details
field.
{
"code": 400,
"errno": 109,
"error": "Bad Request",
"message": "Invalid posted data",
"info": "https://server/docs/api.html#errors",
"details": [
{
"description": "42 is not a string: {'name': ''}",
"location": "body",
"name": "name"
}
]
}
Conflict errors¶
When concurrent requests are manipulating the same resource, it can happen that some database transactions overlap and end up as integrity constraint violations.
In this case, a 409 Conflict
error response is returned. Retrying the same request
will usually be enough to get over it.
{
"code": 409,
"errno": 122,
"error": "Conflict",
"message": "Integrity constraint violated, please retry.",
}