Getting started
Errors
An HTTP status and a body with two fields.
The shape
A failure is an HTTP status and a body with two fields: error, a stable slug you can
switch on, and message, a sentence for a person that names the field at fault, if
any. A 401 also carries WWW-Authenticate: Bearer. An unknown path under the base URL
answers 404 in the same shape.
Response · 400
{
"error": "invalid_request",
"message": "Invalid body at \"endDate\": endDate must be after startDate."
}The codes
| Status | error | When |
|---|---|---|
| 400 | invalid_request | A field is missing or malformed. The message names it. |
| 401 | unauthorized | Missing, expired or revoked credentials. Fetch a new token. |
| 404 | not_found | Unknown id, an unpublished listing, or a path that does not exist. |
| 409 | conflict | The request is well-formed but the record is not in a state that allows it. |
| 413 | payload_too_large | A document over 25 MB. |
| 415 | unsupported_media_type | A document that is not a PDF. |
| 429 | rate_limited | Too many requests, or the organisation’s daily inquiry allowance is spent. |
| 500 | internal_error | Ours. Retry later; if it persists, write to us. |
Retrying
- Reads are safe to retry. After a 500 or a timeout on a GET, wait a moment and try again.
- Creating an inquiry is not. A
POSTthat timed out may have landed, and a retry can create a second inquiry. - A 4xx is yours. Fix the request before sending it again. After a 401, mint a new token instead; after a 429, wait.