Codici di errore

Formato errori HTTP e cause frequenti.

Le risposte di errore seguono un JSON uniforme:

{
  "statusCode": 403,
  "message": "Missing required API key scope: email:send",
  "path": "/emails/send",
  "timestamp": "2026-06-30T12:00:00.000Z"
}

Codici HTTP

Codice	Significato
400	Validazione fallita (campo obbligatorio, email non valida)
401	JWT o API key non valida / scaduta
403	Scope insufficiente, ruolo o tenant non autorizzato
404	Risorsa non trovata
409	Conflitto (duplicato, stato non valido)
413	Messaggio troppo grande (MIME > 10 MB)
422	Regola di business (es. destinatario soppresso)
429	Rate limit globale o quota mensile superata

Codici di errore applicativi

Ogni risposta di errore include anche un code leggibile dalla macchina oltre allo stato HTTP. Codici comuni:

Codice	Significato
`VALIDATION_ERROR`	Un campo ha fallito la validazione (400)
`HTML_BODY_REQUIRED`	Nessun `html`/`htmlBody` e nessun template (400)
`BATCH_LIMIT_EXCEEDED`	Piu di 100 destinatari in una chiamata (400)
`HAS_EMAIL_HISTORY`	Impossibile eliminare una versione template o progetto con storico invii — i log sono append-only (400)
`TEMPLATE_NOT_FOUND`	Slug o id template sconosciuto (404)
`TEMPLATE_NOT_PUBLISHED`	Il template non ha una versione pubblicata da inviare
`EMAIL_TOO_LARGE`	Il messaggio costruito supera il limite di 10 MB (413)
`QUOTA_EXCEEDED`	Quota email mensile superata (429)

Quota superata (429)

Quando superi il 110 % del limite mensile:

{
  "statusCode": 429,
  "message": "Monthly email quota exceeded (115%). Upgrade your plan to continue sending.",
  "quota": {
    "limit": 100,
    "used": 115,
    "percentage": 115
  }
}

Rate limit

In produzione: ~300 richieste/minuto per IP o utente JWT (configurabile). Header:

X-RateLimit-Limit: 300
X-RateLimit-Remaining: 287
X-RateLimit-Reset: 1719763200

Le route di auth pubblico (/auth/login, /auth/register) hanno un limite piu restrittivo: 15 richieste / 15 minuti.

SDK

Il pacchetto mailingcore-js lancia MailingCoreError con .status e .detail per la gestione lato client.