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",
    "requestId": "0192f1c4-…"
  }
}

requestId is also the X-Request-Id header, on every response, not only errors. Quote it when you contact support: it identifies the request in Kirora’s 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. Two members are optional:

• errors lists each field the request got wrong, on VALIDATION_ERROR and DRAFT_INCOMPLETE.
• details carries what else a code reports, such as the limit a PLAN_LIMIT_REACHED hit or the field an ALREADY_EXISTS names. Its shape depends on the code, as the catalogue below says.

A VALIDATION_ERROR lists the fields it found wrong the same way, whether the request’s schema or a later rule found them. A refusal about the request as a whole, rather than a field (an expired form token, an address whose domain takes no mail), has only its message:

{
  "error": {
    "code": "VALIDATION_ERROR",
    "message": "Some request values are invalid. Check the field errors.",
    "errors": [
      { "in": "body", "field": "subject", "code": "too_big", "message": "Use at most 998 characters.", "maximum": 998 }
    ],
    "requestId": "0192f1c4-…"
  }
}

in is body, query, params or headers when known; field is dotted (blocks.0.text) and empty for the part as a whole; code is the schema rule that failed, or custom for a rule checked after the schema (a consent statement missing, an expiry in the past). Request bodies are strict: a field the operation does not take is refused, not ignored.

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 the dashboard, the AI console and 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 errors, fix those fields, and send again. A misspelled or unsupported field is one of them.

SCOPE_MISSING — the key lacks a scope the route needs (HTTP 403; details.requiredScope names it). Solution: create a key with that scope, where your key kind allows it.

AGENT_KEY_REFUSED — an agent key asked for something agents may not do, whatever its scopes, such as sending (HTTP 403). Solution: none in code; a person does it in the dashboard (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 — email.template 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 409). Solution: verify the domain under Settings › Email sending, or send from an address on a domain that is already verified.

What to retry

A 405 (METHOD_NOT_ALLOWED) lists the methods the path takes in its Allow header. A 413 (PAYLOAD_TOO_LARGE) means the body is over the route’s limit; see Request size. A 415 (UNSUPPORTED_MEDIA_TYPE) means the Content-Type is wrong: send application/json (multipart/form-data for an upload).

A request rejected before it runs, such as a validation, missing-scope or rate-limit error, reserves no Idempotency-Key. A refusal returned once the operation has started can be stored and replayed for that key, so after fixing its cause, send it with a new key, following the operation’s retry note. (A send refused for its recipient may still have created the contact; see Idempotency.) A 5xx or a timeout may have done the work: retry only where the operation is safe to repeat. Each operation’s retry note (x-retry) says whether it is. 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