Errors

{
  "statusCode": 422,
  "name": "missing_required_field",
  "message": "Missing required field: subject."
}

statusCode repeats the HTTP status, name is the stable identifier to branch on, and message is a sentence for a human. Messages are written to be readable and may be reworded; names are part of the contract and are not.

Validation failures add an errors array naming each field that failed. It is additive — code that ignores it keeps working.

{
  "statusCode": 400,
  "name": "validation_error",
  "message": "Unknown fields: is_admin, priority.",
  "errors": [
    { "path": "is_admin", "message": "Unknown field: is_admin." },
    { "path": "priority", "message": "Unknown field: priority." }
  ]
}

One error carries a fourth field: a missing User-Agent answers with code: 1010. No other response has it, so it can be matched exactly.

Two names appear more than once, with different statuses, because the situation genuinely differs — the status is what tells them apart, so branch on both.

• validation_error is 400 when a field is wrong, 403 when the request is well-formed and not allowed — an unverified sending domain, a missing User-Agent, a policy restriction — and 422 when the body is fine and the resource itself refuses it, such as a plan limit reached.
• restricted_api_key is 401 when a sending_access key is used on an endpoint that is not sending, and 403 when the key has been revoked. The first is the wrong key for the job; the second is a key that no longer works at all.

missing_api_key and invalid_api_key are both 401 and differ in what you sent. The first means no usable Authorization: Bearer header arrived; the second means a token did arrive and matches nothing live, so check the value rather than your environment.

not_implemented at 501 is not a mistake on your side either. It means the route is ours and reserved for a later phase — it exists so an SDK gets a straight answer rather than a 404 that would imply something about the id it asked for.

The OAuth flow's routes answer in the shape OAuth libraries already parse instead: POST /oauth/token and POST /oauth/revoke use RFC 6749 §5.2's, and /oauth/register and its management routes RFC 7591 §3.2.2's. Branch on error; the description is for a human.

{
  "error": "invalid_grant",
  "error_description": "The authorization code has expired."
}

One refusal in the flow is not a body at all. GET /oauth/authorize with an unknown client or an unregistered redirect URI answers 400 with an error page and never redirects; every other authorize failure redirects back to the client with error and state. And an invalid_token from client management also carries WWW-Authenticate: Bearer error="invalid_token".

Every other route — /oauth/grants included, and any endpoint called with an OAuth access token — answers with the Rasket error body above.

rate_limit_exceeded and 503 are worth retrying, with backoff — a rate_limit_exceeded tells you exactly how long to wait in its retry-after header. The quota 429s — daily_quota_exceeded, monthly_quota_exceeded and marketing_quota_exceeded — carry no retry-after and do not clear until the quota resets or the plan changes. 500 is worth one retry with an idempotency key, and worth reporting if it persists. Everything in the 4xx range other than rate_limit_exceeded describes something about the request that will not change on its own; retrying it unchanged will fail again.