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. At most 20 rows are returned; fix those and re-submit to see any others. A batch array over its cap (100 items on /v1/emails/batch and /v1/sms/batch, including a bulk-shape to; 1,000 contacts on POST /v1/audiences/{id}/contacts) is refused on its length alone, before any item is validated, with a single too_big row.

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.

Send-failure text

When a send fails at the provider or inside Sendoka, the reason stored in error_message (on GET /v1/emails/{id} and GET /v1/sms/{id}), on the failed entry of status_history[], in a message.failed webhook's data.error, in a batch item's error.message, in a verification's delivery_error, and in a dashboard template test-send's error is one of a fixed set of sentences, never the raw provider or database exception, which can name internal account details. Examples:

• Email address is not verified. The following identities failed the check: … (the identities are your own from address or domain, or the recipient)
• The provider could not use the domain's custom MAIL FROM setup
• Provider rate exceeded; safe to retry / Provider sending quota reached
• The SMS provider rejected the message (DESTINATION_PHONE_NUMBER_OPTED_OUT) (the bracketed reason is the provider's documented reason code)
• Attachment url could not be fetched: fetch failed 404
• The message could not be sent because of an internal error

Refusals Sendoka raises itself (a paused IP pool, the India DLT guard, an oversized attachment) keep their own wording. Bounce and complaint text from delivery callbacks (Bounce: Permanent (General) — …) is unchanged.

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: 1713820800000
X-RateLimit-Plan: pro
X-RateLimit-Scope: org | key

Recovery recipes