API errors

Every error response follows the same shape:

{
  "error": {
    "type": "validation_error",
    "message": "Subject is required",
    "code": "VALIDATION_ERROR",
    "request_id": "req_Hg8JpNvKXWg4f",
    "errors": [
      { "path": ["to", 0], "code": "invalid_string", "message": "Invalid recipient email" }
    ]
  }
}

• type — coarse category, one of five values (below). It does not map 1:1 to the HTTP status — branch on code and the status, not on type.
• code — stable identifier for programmatic handling; see catalog.
• message — human string; may reference the first field issue.
• request_id — injected by withApiAuth on every /v1 error response; also emitted as the X-Request-Id header. Include in support tickets.
• errors[] — present on validation errors from a Zod schema. Each row has path (array of keys / indexes), code (Zod issue code), message.

Types

type says which kind of thing went wrong; the HTTP status says whether it is worth retrying. The two are set independently, so the same type is seen under several statuses:

Full code catalog

Authentication — 401 / 403

Validation — 409 / 413 / 422

Rate / quota — 429

Not found — 404

Server — 500

Provider — 502

When a downstream provider (AWS SES / SNS / Stripe) returns an error we couldn't classify, you'll see type: "server_error" with a 502 and the provider's message copied into message. Log the request_id and the provider trace if possible.

Codes the sections above do not list

Every code below is emitted by a /v1 route or by src/lib/api/* today (grep apiError( / validationError(), grouped by type. Same columns as the tables above.

authentication_error

validation_error

rate_limit_error

server_error

Per-item codes inside a batch response

These appear in data[].error.code of /v1/emails/batch and /v1/sms/batch, never as a top-level error.code. The HTTP status of the batch itself is 200.

Reading validation errors

try {
  await mr.emails.send({ from, to, subject, html });
} catch (err) {
  if (err.code === "VALIDATION_ERROR") {
    for (const issue of err.errors ?? []) {
      console.log(issue.path.join("."), issue.message);
    }
  } else if (err.code === "RATE_LIMITED") {
    await new Promise((r) => setTimeout(r, reset - Date.now()));
  }
}

Headers

Returned on every response, not just 429:

X-Request-Id: req_Hg8JpNvKXWg4f
X-RateLimit-Limit: 600
X-RateLimit-Remaining: 598
X-RateLimit-Reset: 1713820800
X-RateLimit-Plan: pro
X-RateLimit-Scope: org | key

Recovery recipes