Reading an error
Every error is RFC 9457 application/problem+json. A real one, captured from
the API:
{
"type": "about:blank",
"status": 400,
"title": "Missing Idempotency-Key",
"detail": "All /v1/send calls require an Idempotency-Key header (any unique string per send, 24h dedupe window).",
"code": "missing_idempotency_key",
"request_id": "921f3d72-2618-4c05-a341-e29de4a385c6"
}
| Field | Branch on it? | |
|---|---|---|
code |
yes, first | machine-readable, derived from the title |
status |
yes | the class of failure |
title |
for logs | specific and human; code is the one to match |
detail |
no | written for a person, wording changes |
request_id |
no | keep it, quote it in support |
type |
no | always about:blank |
The identifier to branch on
Every error carries a code: a machine-readable identifier derived from the
title at the single place problem documents are written.
{ "status": 403, "title": "Insufficient scope", "code": "insufficient_scope" }
Branch on code. It is lowercase and underscore-separated, and a run of
spaces or punctuation collapses to one separator, so Allow-list full and
Allow list full produce the same code and always will.
The full set is frozen in the repository and checked in CI, so an error that appears, disappears or is reworded shows up as a visible diff rather than a silent contract change.
Titles are not the generic HTTP phrases
Worth stating because it is the mistake the older version of our own error
page made: the API does not return "title": "Bad Request" or
"title": "Unauthorized". Titles name the specific failure.
| Status | Examples of what you will actually see |
|---|---|
| 400 | Invalid JSON body, Missing Idempotency-Key, Invalid variables, Attachment too large |
| 401 | Missing Bearer token, Invalid API key, Revoked API key |
| 403 | Insufficient scope, Business mode required, Upgrade required, Sender not authorised, Not allowed on a test key |
| 404 | Not found, Mailbox not found, Domain not found, Message not found |
| 409 | Address already in use, Alias address already exists, Account not active |
| 429 | Too many attempts, Reply loop detected, plus the send rate cap |
| 500 | Internal error |
| 502 | Queue error |
| 503 | Billing not configured |
Where to go next
| Symptom | Page |
|---|---|
| 401 or 403 on the key itself | Authentication errors |
| 400 on the body | Bad requests |
| the send was refused | Rejected sends |
| the attachment was refused | Attachment errors |
| 429 | Rate limits |
| the same send happened twice | Idempotency |
| timeouts, 500s, connection resets | Timeouts and server errors |
| the template rendered wrongly | Template errors |
| your webhook signature will not verify | Signature verification |
| events are not arriving | Reliability |
| accepted but never delivered | Debugging a failed request |
| DNS will not verify | DNS troubleshooting |