Error Codes Reference

The API returns a small set of error codes. They are deliberately generic: the code tells you the class of problem and the HTTP status, while message carries the specific detail.

Branch on code, not on message: messages are written for humans and can change without notice.

Error Format

{
  "error": {
    "code": "NOT_FOUND",
    "message": "Webhook 'wh_abc123' not found.",
    "docs": "https://docs.tratto.email/en/docs/error-codes"
  }
}

suggestion is present on some errors with a hint about the fix. Validation errors add a details array: see below.

The Codes

BAD_REQUEST (400) vs VALIDATION_ERROR (422)

Both mean "your request was wrong", and they fail at different stages:

• BAD_REQUEST (400) — the request never reached a handler. The body could not be parsed at all: malformed JSON, a truncated payload, a Content-Type that says JSON over something that isn't. There is no details array, because no schema ever ran.
• VALIDATION_ERROR (422) — the body parsed, then failed the schema. This is the one that tells you which field is wrong.

Validation errors

VALIDATION_ERROR returns 422 and includes a details array from the schema validator identifying each field that failed:

{
  "error": {
    "code": "VALIDATION_ERROR",
    "message": "Request validation failed.",
    "docs": "https://docs.tratto.email/en/docs/error-codes",
    "details": [
      {
        "path": "/to",
        "message": "Invalid email"
      }
    ]
  }
}

Markdown validation

The markdown support on POST /v1/emails and on templates adds two VALIDATION_ERROR (422) cases worth knowing:

• markdown and html together. The two fields are mutually exclusive everywhere. On POST /v1/emails the message is "markdown and html are mutually exclusive — provide one or the other."; on templates, html is rejected outright for format: "emailmd" ("html is not accepted when format is 'emailmd' — the HTML is derived from the markdown render.") and markdown requires that format.
• Empty markdown. A markdown field that is empty or whitespace-only fails with "markdown must not be empty." — the render never runs on empty input.

Two codes share 429

RATE_LIMITED and QUOTA_EXCEEDED both return 429, and they need opposite responses:

• RATE_LIMITED: you are sending too fast. Back off and retry; the request will succeed shortly. See Rate Limits.
• QUOTA_EXCEEDED: you have hit a usage limit, such as the monthly email quota. Retrying will not help until the limit resets, a domain is deleted, or the plan is upgraded.

Work that runs in the background never answers with this code. A campaign the dispatcher cannot fit in the remaining quota, before it starts or mid-send, is paused with pausedReason: "quota_exceeded" (see Campaigns); resuming it later reaches only the recipients it missed. A flow whose send step finds the quota exhausted skips that email and moves on: the email is not sent later.

Treating them the same means retrying forever against a quota wall:

if (error.status === 429) {
  if (error.code === 'QUOTA_EXCEEDED') {
    // Alert someone. Retrying cannot fix this.
    throw error;
  }
  await backoff();
  return retry();
}

Handling errors with the SDK

@tratto/email throws TrattoError, which carries code and statusCode:

import { TrattoError } from '@tratto/email';

try {
  await tratto.emails.send({ /* … */ });
} catch (error) {
  if (error instanceof TrattoError) {
    switch (error.code) {
      case 'VALIDATION_ERROR':
        // Fix the payload: retrying unchanged will fail again.
        break;
      case 'RATE_LIMITED':
        await backoff();
        break;
      case 'QUOTA_EXCEEDED':
        // Nothing to retry.
        break;
      default:
        throw error;
    }
  }
}

Next: Rate Limits · Idempotency