Every error has one shape, so a client can read it the same way each time. You will be able to find any code and its remedy.
The shape #
{"error":{"code":"validation_failed","message":"Missing: name.","fields":["name"],"request_id":"9f2c1a4b7d3e8a60"}}code: the stable word to program against.message: plain text for a person.fields: the fields at fault, when there are any.request_id: quote it to support. It matches theX-Request-Idheader on the response, and you can send your own (8 to 64 letters, digits, dot, hyphen or underscore).
Success shapes: a record is {"data":{...}}, a list is {"data":[...]}, a page adds next_cursor, and an action returns fields such as {"ok":true}. A new record answers 201.
The codes #
| HTTP | Code | Meaning and fix |
|---|---|---|
| 400 | invalid_json | The body is unreadable JSON. Fix the syntax. |
| 400 | invalid_cursor | The paging cursor is unrecognised. Start again from the first page. |
| 401 | unauthorized | No token, a malformed token, an ended or revoked token, or an inactive account. Sign in again. |
| 401 | invalid_credentials | The email and password pair failed. Wait a few minutes and try again. |
| 401 | totp_required | Add the 6 digit code in the totp field. |
| 401 | totp_enrolment_required | Set up the authenticator app first. |
| 403 | forbidden | The role or the key scope excludes the action. Messages: "Ask the owner if you need access.", "This key is read-only.", "This key is for towing dispatch only." |
| 403 | licence_read_only | The licence allows reading and exporting only. Reads still work. See the licence articles. |
| 403 | password_change_required | A one-time password is still in use. Send a new password to /auth/change-password. |
| 404 | not_found | No record, path or link matches. |
| 405 | method_not_allowed | The path takes other methods. |
| 409 | conflict | The request clashes with the current state: a rule refusal (for example an assignment), a repeated set-up, or an idempotency key used for another request. |
| 409 | no_driver | The account has no active driver record. |
| 413 | validation_failed | An upload is over 60 MB. |
| 414 | uri_too_long | The address is over 2000 characters. |
| 422 | validation_failed | A field is missing or invalid. fields names it. |
| 422 | invalid_date | A date needs ISO 8601 form. |
| 422 | vin_failed | The VIN failed its check, or needs details by hand. |
| 422 | upload_failed | Every photo failed the checks. |
| 429 | rate_limited | Too many requests. Wait a minute. The Retry-After header says 60. |
| 429 | locked | Too many failed sign-ins. Wait a few minutes. |
| 500 | server_error | A fault on the server. The detail is in the server log. Try again, and quote the request_id. |
| 503 | safe_mode | The server is read only after repeated crashes, or a safety check paused changes. Reads, exports and (in safe mode) backups still work. See the safe mode article. |
Also useful #
- Unknown paths answer 404
not_foundwith "No such path." and OPTIONS answers 204. - Every response carries
Cache-Control: no-store. A GET that returns 200 carries anETag, and a repeat withIf-None-Matchcan answer 304. - Times are UTC in the form
YYYY-MM-DDTHH:MM:SSZ. Lists takelimitfrom 1 to 100 (25 by default), an opaquecursorandupdated_since.
If something goes wrong #
Send the request_id and the time to your administrator. See "Server health".