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)
422	Regola di business (es. destinatario soppresso)
429	Rate limit globale o quota mensile superata

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.