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"
      }
    ]
  }
}

With API 0.24.0 or later, POST /v1/emails and PATCH /v1/emails/{id} also reject a field they do not know: the entry has path / for a field at the top level of the body, and a message that names it, such as Unrecognized key: "reply_to". See Unknown fields.

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.

TEMPLATE_NOT_PUBLISHED (422)

A template has to be published before it can be used to send. This is a code of its own, not a flavour of VALIDATION_ERROR: it carries no details array, because no schema rejected the body. It is returned by POST /v1/campaigns, by a PATCH /v1/campaigns/:id that swaps in a template, and by POST /v1/flows/:id/activate:

{
  "error": {
    "code": "TEMPLATE_NOT_PUBLISHED",
    "message": "Template 'tmpl_abc123' is not published and cannot be used to send.",
    "docs": "https://docs.tratto.email/en/docs/error-codes",
    "suggestion": "Publish the template first: PATCH /v1/templates/:id with { \"status\": \"published\" }, or use the Publish button in the template editor."
  }
}

On flow activation the message names the step that carries the template: Template 'tmpl_abc123' on step 's0' is not published and cannot be used to send.

A templateId that does not exist is a NOT_FOUND (404) instead. The template test send is exempt, and POST /v1/emails is not refused at all: it accepts the request and the email fails at delivery. See Templates.

NO_WORKSPACE (403)

A dashboard session (a signed-in account, not an API key) whose account has no workspace gets this code on every authenticated route, except the two that accept an invitation, the one that creates a workspace and the one that lists them: GET /v1/workspaces answers 200 with {"data":[]}, with or without beta access. The beta access check runs first: an account without beta access gets that error instead.

{
  "error": {
    "code": "NO_WORKSPACE",
    "message": "This account has no workspace.",
    "docs": "https://docs.tratto.email/en/docs/error-codes"
  }
}

There is no suggestion. Accepting the beta invitation does not create a workspace, and neither does GET /v1/workspace. In the dashboard this code opens the "This account has no workspace" page: the "Create your workspace" button creates one and takes you into it. From there you can also sign in with another account or try again.

The button calls POST /v1/workspaces, which accepts a dashboard session only. It returns 201 with the same object as GET /v1/workspace. The name field is optional (1 to 100 characters, default My Workspace): an invalid name gets 422. The same route creates the workspaces beyond the first, within the limit of the plan; the refusals are listed in Workspaces. Workspaces created this way have ids starting with ws_; existing workspaces keep their id.

API keys are not affected: a key always belongs to a workspace, and a key cannot create one (POST /v1/workspaces returns 403).

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 or a workspace is deleted, a place in the workspace is freed, or the plan is upgraded.

The monthly email quota, the domain limit and the AI generations belong to the account that owns the workspace, and every workspace of that account draws on them. A QUOTA_EXCEEDED can come from another workspace of the same account or from another member, and its message says that the limit is shared across the account. See Rate Limits.

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" (one of the four values listed in 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

Both SDKs raise a TrattoError carrying the code and the HTTP status, and each exposes part of the rest of the payload: the Node SDK adds docs, the Python SDK adds suggestion and docs from 1.2.0 or newer. Branch on the code; read suggestion when one code covers more than one situation.

Node.js

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

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 'TEMPLATE_NOT_PUBLISHED':
        // Raised by the campaign and flow calls. Publish the template,
        // then make the call again: retrying as is cannot help.
        break;
      case 'RATE_LIMITED':
        await backoff();
        break;
      case 'QUOTA_EXCEEDED':
        // Nothing to retry.
        break;
      default:
        throw error;
    }
  }
}

Python

tratto-email raises TrattoError with code, status_code, suggestion and docs. The last two need 1.2.0 or newer and are None when the response omits them:

from tratto import TrattoError

try:
    client.campaigns.unschedule('camp_xyz789')
except TrattoError as e:
    print(e.code)          # 'CONFLICT'
    print(e.suggestion)    # what to do instead, in the API's own words
    print(e.docs)          # link to this page

PHP

tratto/email throws TrattoException with errorCode, statusCode, suggestion and docs. The last two are null when the response omits them:

use Tratto\TrattoException;

try {
    $tratto->campaigns->unschedule('camp_xyz789');
} catch (TrattoException $e) {
    echo $e->errorCode, "\n";   // 'CONFLICT'
    echo $e->suggestion, "\n";  // what to do instead, in the API's own words
    echo $e->docs, "\n";        // link to this page
}

This is the case suggestion exists for: the 409 on campaigns.send and on campaigns.unschedule is one code covering several states, and only the text says which one you hit. See Campaigns.

Next: Rate Limits · Idempotency