Getting started
Errors
A status that means what it says and a body with two fields.
The shape
A failure is a status that means what it says and a body with two fields: error, a stable slug you can switch on, and message, a sentence for a
person, naming the field where one is at fault. A 401 also carries WWW-Authenticate: Bearer. Unknown paths under the base URL answer the same shape with
404 rather than an HTML page.
Response · 400
{
"error": "invalid_request",
"message": "Invalid body at \"checkOut\": checkOut must be after checkIn."
}The codes
| Status | error | When |
|---|---|---|
| 400 | invalid_request | A field is missing or malformed. The message names it. |
| 401 | unauthorized | No bearer, an expired one, or one whose credentials were revoked. 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 | The organisation’s daily enquiry allowance is spent. |
| 500 | internal_error | Ours. Retry later; if it persists, write to us. |
Each endpoint’s reference page lists the failures it can actually produce, with the condition behind each.
Retrying
- Reads are safe to retry. Every GET can be repeated at will; a 500 or a timeout on one is a reason to try again after a moment.
- Reporting an agreement is idempotent. A
PUTwith the sameexternalIdupdates the same envelope, so a lost response is fixed by sending the report again. - Creating an inquiry is not. A
POSTthat timed out may have landed. Rather than retrying blindly, look for it: the inquiry carries yourmetadata, so put a request id there. - A 4xx is yours. Fix the request; the same request will fail the same way. A 401 is the one exception: mint a new token and send it again.