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

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.

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 email. Riprovare non serve finché il limite non si azzera, non elimini un dominio o non passi a un piano superiore.

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" (vedi 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

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

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 'RATE_LIMITED':
        await backoff();
        break;
      case 'QUOTA_EXCEEDED':
        // Non c'è nulla da riprovare.
        break;
      default:
        throw error;
    }
  }
}

Prossimo: Rate Limit · Idempotenza