Errors

The error body

A non-2xx response is always this shape:

{
  "error": "validation_error",
  "message": "body/to/0 Invalid email address",
  "details": [
    {
      "keyword": "invalid_format",
      "instancePath": "/to/0",
      "schemaPath": "#/to/0/invalid_format",
      "message": "Invalid email address",
      "params": {
        "origin": "string",
        "format": "email"
      }
    }
  ]
}

error is a stable, machine-readable slug: safe to branch your code on. message is for humans and may be reworded at any time; don't match on its text. details is present only on some errors (mainly validation failures). For a route whose body, params, or query are validated by an attached schema, essentially every route in this reference, it's the array shown above, produced by the validator itself: each entry carries keyword/instancePath/schemaPath/message/params, not code/path. Two routes validate their body by hand instead of through an attached schema and still return the older {code, path, message, ...} issue shape: PUT /api/settings and POST /v1/sandbox/messages/:id/simulate. And one check runs after schema validation has already passed, so it answers in its own shape: POST /v1/emails/send rejecting a reserved or malformed custom header returns {field, message} entries naming the offending fields. So branch on error first and treat details as advisory, reading a key that a given entry happens not to carry is the one way to get this wrong.

The error slugs

Every error the API returns, including a bare validation failure that never reaches a route handler, is mapped to exactly one of these. There are 16; the two pairs that share an HTTP status (quota_exceeded/rate_limited both 429, sandbox_unavailable/service_unavailable both 503) are deliberately kept as separate slugs rather than collapsed, because the correct client response to each half of a pair differs.

Query strings are strict

Every documented endpoint validates its query string against a fixed schema. An unknown query parameter, or a parameter repeated more than once, is a 400 validation_error, never a silently ignored typo. This applies even to routes that take no query parameters at all: a stray ?debug=1 on a route that accepts none is still rejected.

Request bodies are strict too

Most documented request bodies reject an unrecognised field outright rather than silently dropping it: the same 400 validation_error. Sending a field the API doesn't know about is a bug worth surfacing, not a no-op.

Rate limits and Retry-After

A 429 rate_limited response carries a Retry-After header (seconds) telling you exactly when the per-minute window resets. Wait that long and retry. A 429 quota_exceeded response does not carry one: a monthly quota isn't something a short wait fixes, so there's no meaningful delay to advertise. X-RateLimit-Limit, X-RateLimit-Remaining, and X-RateLimit-Reset are not sent on every response. They come from a rate limiter, so they appear only where one is attached, and on every response from such a route rather than just the rejections. On the surface documented here that is two routes: POST /v1/emails/send, carrying the per-minute send limit your plan sets, and POST /v1/domains/:id/verify, carrying a separate per-account ceiling on DNS re-checks. Read them where you find them; don't build back-pressure that assumes every response has them.