Errors

Every error — validation, authentication, conflict, server fault — comes back in one shape, with the HTTP status set appropriately:

{
  "error": {
    "code": "CONFLICT",
    "message": "Only draft campaigns can be changed or sent",
    "details": { },
    "requestId": "0192f1c4-…"
  }
}

requestId is also the X-Request-Id header, on every response, not only errors. Quote it when you contact support: it finds the request in our logs.

code is a stable machine-readable identifier — branch on this. message is human-readable English intended for logs and developers, not for end users; its wording may change at any time. details is optional and its shape varies by code.

The catalogue

These are the codes a /v1 client can receive.

The API defines more codes than these, but the rest are reachable only from cookie-session surfaces — the dashboard, the AI console, account management — and a server-to-server client will never see one. They are deliberately left out of this list so no SDK carries a dead exception type.

Scopes, agent keys and IP restrictions are explained in Authentication, and IDEMPOTENCY_KEY_REUSED in Idempotency.

Common problems

VALIDATION_ERROR — the body, query or path failed validation (HTTP 400). Solution: read details for the field errors, fix those fields, and send again.

FORBIDDEN — the key lacks a scope the route needs (HTTP 403, message “API key lacks the <scope> scope”). Solution: create a key with that scope, or add it where your key kind allows; an agent key is also refused on send routes whatever its scopes (see Authentication).

IDEMPOTENCY_KEY_REUSED — the same Idempotency-Key arrived with a different payload (HTTP 409). Solution: repeat the original request exactly to retry it, or use a new key for a genuinely different send.

TEMPLATE_NOT_PUBLISHED — templateId names a template with no published version (HTTP 409). Solution: publish the template, then retry with the same Idempotency-Key.

RATE_LIMITED — too many requests for the budget (HTTP 429). Solution: wait Retry-After seconds and retry with backoff; see Rate limits.

SENDING_DOMAIN_UNVERIFIED — the from-address is not on a verified sending domain (HTTP 403). Solution: verify the domain under Settings → Email → Domains, or send from an address on a domain that is already verified.

What to retry

Retrying is only safe when the operation is idempotent. Read Idempotency before building retry logic into a write path.

Mapping errors in an SDK

Model code on the catalogue above. Then:

• Expose code as a typed value, not a bare string.
• Keep the unparsed details reachable — clients need the field errors inside a VALIDATION_ERROR, and no typed wrapper will anticipate every shape.
• Include the HTTP status and, where available, a request identifier on the exception.
• Handle an unrecognised code without crashing. New codes are additive and can appear before your SDK is updated; fall back to a generic error carrying the raw code rather than throwing a parse failure.

Next steps

• IdempotencyRetry writes without repeating them
• Rate limitsBack off on 429
• AuthenticationScopes and key kinds
• WebhooksFailures that arrive after the request