Errors

When a request fails, Dairo returns one predictable shape and a stable code that says exactly what went wrong, so your app or your agent can react instead of parsing English.

{
  "error": {
    "type": "invalid_request_error",
    "code": "invalid_domain",
    "message": "domain is not verified",
    "param": null
  }
}

A few structured errors add a details object. Deleting a domain that still owns inboxes returns 409 with code cascade_confirmation_required and details: { requiresCascadeConfirmation, inboxes, messages }, so a client can prompt before deleting.

The full code list

Every code an API key request can return, with its typical HTTP status:

Some endpoints return a more specific code for a particular condition, in the same envelope: letter_not_cancelable (409, a letter already dispatched), letter_content_clipped (422, param templateId: a template letter's rendered text is cut off, so it is not printed), upload_link_consumed (409, a one-time upload link reused), and cascade_confirmation_required (409, the domain-delete case above).

Plan limits on resource counts

Creating an inbox (including connecting a Telegram bot), a domain, or a storage bucket beyond your plan's count is a 429 whose message names the limit, for example Your inbox plan limit is reached (3/3). Today that response carries the code rate_limited, not plan_limit_reached. Waiting does not clear it: remove an unused resource or upgrade the plan, and compare usage with limits from GET /v1/whoami before you create more.

The type classes

type groups codes into a coarse class, so you can switch at a high level before drilling into code:

Handling errors in the SDKs

The SDKs raise a typed DairoError that surfaces status, type, code, param, and (when present) requestId. Branch on code:

import { DairoError } from "dairo";

try {
  await dairo.messages.send({ inboxId: "inbox_123", to: "x@example.com", subject: "Hi", text: "…" });
} catch (err) {
  if (err instanceof DairoError) {
    switch (err.code) {
      case "invalid_domain":   /* verify the sending domain */ break;
      case "scope_missing":    /* this key can't send mail */ break;
      case "rate_limited":     /* back off and retry */ break;
      default:                 console.error(err.type, err.code, err.message, err.param);
    }
  }
}