Riferimento Codici di Errore

L'API restituisce un piccolo insieme di codici di errore. Sono volutamente generici: il codice indica la classe del problema e lo stato HTTP, mentre message contiene il dettaglio specifico.

Fai i controlli su code, non su message: i messaggi sono scritti per le persone e possono cambiare senza preavviso.

Formato degli Errori

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

suggestion è presente su alcuni errori con un'indicazione su come risolvere. Gli errori di validazione aggiungono un array details: vedi sotto.

I Codici

BAD_REQUEST (400) e VALIDATION_ERROR (422)

Entrambi significano «la tua richiesta è sbagliata», ma falliscono in due momenti diversi:

• BAD_REQUEST (400) — la richiesta non è mai arrivata a un handler. Il corpo non è stato interpretabile: JSON malformato, payload troncato, un Content-Type che dichiara JSON su qualcosa che non lo è. Non c'è array details, perché nessuno schema è stato eseguito.
• VALIDATION_ERROR (422) — il corpo è stato letto e poi ha fallito lo schema. È questo a dirti quale campo è sbagliato.

Errori di validazione

VALIDATION_ERROR restituisce 422 e include un array details prodotto dal validatore dello schema, che identifica ogni campo non valido:

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

Con l'API 0.24.0 o successiva, POST /v1/emails e PATCH /v1/emails/{id} rifiutano anche un campo che non conoscono: la voce ha path / per un campo al primo livello del body, e un message che lo nomina, come Unrecognized key: "reply_to". Vedi Campi sconosciuti.

Validazione Markdown

Il supporto markdown su POST /v1/emails e sui template aggiunge due casi di VALIDATION_ERROR (422) da conoscere:

• markdown e html insieme. I due campi sono mutuamente esclusivi ovunque. Su POST /v1/emails il messaggio è "markdown and html are mutually exclusive — provide one or the other."; sui template, html viene rifiutato del tutto per format: "emailmd" ("html is not accepted when format is 'emailmd' — the HTML is derived from the markdown render.") e markdown richiede quel formato.
• Markdown vuoto. Un campo markdown vuoto o di soli spazi fallisce con "markdown must not be empty." — il render non gira mai su input vuoto.

TEMPLATE_NOT_PUBLISHED (422)

Un template deve essere published prima di poter essere usato per inviare. È un codice a sé, non una variante di VALIDATION_ERROR: non porta l'array details, perché nessuno schema ha rifiutato il corpo. Lo restituiscono POST /v1/campaigns, una PATCH /v1/campaigns/:id che sostituisce il template e 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."
  }
}

All'attivazione di un flow il messaggio indica anche lo step che usa il template: Template 'tmpl_abc123' on step 's0' is not published and cannot be used to send.

Un templateId inesistente è invece un NOT_FOUND (404). Il test-send del template è esente, e POST /v1/emails non viene rifiutata affatto: accetta la richiesta e l'email fallisce in consegna. Vedi Template.

NO_WORKSPACE (403)

Una sessione della dashboard (un account che ha effettuato l'accesso, non una chiave API) il cui account non ha un workspace riceve questo codice su ogni rotta autenticata, tranne le due che accettano un invito, quella che crea il workspace e quella che li elenca: GET /v1/workspaces risponde 200 con {"data":[]}, con o senza accesso alla beta. Prima viene il controllo dell'accesso alla beta: un account senza accesso alla beta riceve quell'errore.

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

Non c'è suggestion. Accettare l'invito alla beta non crea un workspace, e nemmeno GET /v1/workspace. Nella dashboard questo codice apre la pagina «Questo account non ha un workspace»: il bottone «Crea il tuo workspace» lo crea e ti porta dentro. Da lì puoi anche accedere con un altro account o riprovare.

Il bottone chiama POST /v1/workspaces, che accetta solo una sessione della dashboard. Risponde 201 con lo stesso oggetto di GET /v1/workspace. Il campo name è facoltativo (da 1 a 100 caratteri, predefinito My Workspace): un nome non valido riceve 422. La stessa rotta crea i workspace oltre il primo, entro il limite del piano; i rifiuti sono elencati in Workspace. Gli id dei workspace creati così iniziano con ws_; i workspace esistenti tengono il loro id.

Le chiavi API non sono coinvolte: una chiave appartiene sempre a un workspace, e con una chiave non si crea un workspace (POST /v1/workspaces risponde 403).

Due codici condividono il 429

RATE_LIMITED e QUOTA_EXCEEDED restituiscono entrambi 429, ma richiedono reazioni opposte:

• RATE_LIMITED: stai inviando troppo in fretta. Rallenta e riprova: la richiesta andrà a buon fine a breve. Vedi Rate Limit.
• QUOTA_EXCEEDED: hai raggiunto un limite d'uso, come la quota mensile di destinatari. Riprovare non serve finché il limite non si azzera, non elimini un dominio o un workspace, non liberi un posto nel workspace o non passi a un piano superiore.

La quota mensile di email, il limite di domini e le generazioni AI appartengono all'account proprietario del workspace, e tutti i workspace di quell'account vi attingono. Un QUOTA_EXCEEDED può arrivare da un altro workspace dello stesso account o da un altro membro, e il suo message dice che il limite è condiviso dall'account. Vedi Rate Limit.

Il lavoro in background non risponde mai con questo codice. Una campagna che il dispatcher non riesce a far stare nella quota rimasta, prima di partire o a metà invio, viene messa in pausa con pausedReason: "quota_exceeded" (uno dei quattro valori elencati in Campagne); riprenderla più tardi raggiunge solo i destinatari mancati. Un flusso il cui step di invio trova la quota esaurita salta quell'email e prosegue: l'email non viene inviata in seguito.

Trattarli allo stesso modo significa riprovare all'infinito contro un muro:

if (error.status === 429) {
  if (error.code === 'QUOTA_EXCEEDED') {
    // Avvisa qualcuno. Riprovare non può risolvere.
    throw error;
  }
  await backoff();
  return retry();
}

Gestione degli errori con l'SDK

Entrambi gli SDK sollevano un TrattoError che porta il code e lo status HTTP, e ognuno espone una parte del resto del payload: l'SDK Node aggiunge docs, quello Python aggiunge suggestion e docs dalla 1.2.0 o successiva. Dirama sul codice; leggi suggestion quando un codice copre più di una situazione.

Node.js

@tratto/email solleva TrattoError, che espone code, statusCode e docs:

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

try {
  await tratto.emails.send({ /* … */ });
} catch (error) {
  if (error instanceof TrattoError) {
    switch (error.code) {
      case 'VALIDATION_ERROR':
        // Correggi il payload: riprovare invariato fallirà di nuovo.
        break;
      case 'TEMPLATE_NOT_PUBLISHED':
        // Arriva dalle chiamate su campagne e flussi. Pubblica il template,
        // poi rifai la chiamata: riprovare così com'è non serve.
        break;
      case 'RATE_LIMITED':
        await backoff();
        break;
      case 'QUOTA_EXCEEDED':
        // Non c'è nulla da riprovare.
        break;
      default:
        throw error;
    }
  }
}

Python

tratto-email solleva TrattoError con code, status_code, suggestion e docs. Gli ultimi due richiedono la 1.2.0 o successiva e valgono None quando la risposta non li contiene:

from tratto import TrattoError

try:
    client.campaigns.unschedule('camp_xyz789')
except TrattoError as e:
    print(e.code)          # 'CONFLICT'
    print(e.suggestion)    # cosa fare invece, nelle parole dell'API
    print(e.docs)          # link a questa pagina

PHP

tratto/email solleva TrattoException con errorCode, statusCode, suggestion e docs. Gli ultimi due valgono null quando la risposta non li contiene:

use Tratto\TrattoException;

try {
    $tratto->campaigns->unschedule('camp_xyz789');
} catch (TrattoException $e) {
    echo $e->errorCode, "\n";   // 'CONFLICT'
    echo $e->suggestion, "\n";  // cosa fare invece, nelle parole dell'API
    echo $e->docs, "\n";        // link a questa pagina
}

È il caso per cui suggestion esiste: il 409 di campaigns.send e quello di campaigns.unschedule sono un codice solo per più stati diversi, e a dire quale hai incontrato c'è solo il testo. Vedi Campagne.

Prossimo: Rate Limit · Idempotenza