# Errori

> Come l’API di Emailit segnala gli errori. Formati del corpo delle risposte, codici di stato HTTP e il loro significato, e soluzioni per i messaggi di errore più frequenti.

L’API di Emailit usa i codici di stato HTTP per indicarti se una richiesta è andata a buon fine. I codici nell’intervallo `2xx` indicano un successo, i codici `4xx` indicano che qualcosa nella richiesta va cambiato e i codici `5xx` indicano che qualcosa è andato storto da parte nostra. Questa pagina descrive il corpo degli errori, tutti i codici di stato che l’API restituisce e come correggere gli errori più comuni.

## Formati delle risposte di errore

Il corpo di ogni errore è un oggetto JSON con un campo `error`. La forma esatta dipende dal punto in cui la richiesta non è riuscita. Scrivi la gestione degli errori in modo che legga `error`, poi `message` quando è presente, poi gli eventuali campi aggiuntivi documentati dall’endpoint.

### Errori della richiesta

Gli errori di autenticazione, gli errori di permesso, il JSON malformato e gli altri errori generati prima dell’esecuzione di un endpoint usano il formato di errore HTTP standard:

```json
{
  "statusCode": 401,
  "error": "Unauthorized",
  "message": "API key required"
}
```

| Campo | Descrizione |
| --- | --- |
| `statusCode` | Il codice di stato HTTP. |
| `error` | La frase di stato HTTP, come `Unauthorized` o `Forbidden`. |
| `message` | Cosa è andato storto, in linguaggio semplice. |

### Errori di convalida

Quando un parametro di query o un campo del corpo ha il tipo sbagliato, manca o è fuori dall’intervallo consentito, l’API rifiuta la richiesta con `400` prima di eseguirla ed elenca ogni problema in `details`:

```json
{
  "statusCode": 400,
  "error": "Bad Request",
  "message": "Validation error",
  "details": [
    {
      "instancePath": "/limit",
      "schemaPath": "#/properties/limit/maximum",
      "keyword": "maximum",
      "params": { "comparison": "<=", "limit": 100 },
      "message": "must be <= 100"
    }
  ]
}
```

`instancePath` indica il campo (`/limit`, `/to`, `/attachments/0/filename`) e `message` descrive la regola violata. Su alcuni endpoint, come [Invia un’email](/it/docs/api-reference/emails/send/), questi errori restituiscono solo `{"error": "Bad Request"}`.

### Errori delle risorse

Gli errori generati da un endpoint, come un oggetto inesistente o un nome duplicato, restituiscono `error` e spesso `message`:

```json
{
  "error": "Email not found",
  "message": "Email with ID 'em_4KYof1ZzXndZE2VPi0DgULiekG8' not found in your workspace"
}
```

Alcuni errori aggiungono campi che ti aiutano a rimediare:

| Campo | Restituito con | Contiene |
| --- | --- | --- |
| `existing` | `409` quando crei un dominio, una chiave API, una lista, un contatto o un iscritto duplicato | L’oggetto che esiste già, così puoi usare quello. |
| `usage` | `422` quando viene raggiunto un limite del piano | `used`, `limit` e, per le liste, `plan`. |
| `required_plan` | `403` con `error: "plan_required"` | Il piano più basso che include la funzione, come `pro`. |
| `code` | Alcuni errori `403` e `422` | Un codice stabile e leggibile dalle macchine, come `unverified_workspace_recipient` o `events_offset_too_large`. |
| `missing` | `404` da [Aggiorna i contatti in blocco](/it/docs/api-reference/contacts/bulk/) | Gli ID dei contatti non trovati. |

### Errori di convalida dell’invio

[Invia un’email](/it/docs/api-reference/emails/send/) e [Inoltra un’email](/it/docs/api-reference/emails/forward/) controllano l’intero messaggio in una volta e restituiscono tutti i problemi in `validation_errors`:

```json
{
  "error": "Validation failed",
  "validation_errors": [
    "Missing required field: subject",
    "Invalid to email address at index 1: ada@example"
  ]
}
```

### Errori per campo

Template, campagne e automazioni restituiscono i problemi di convalida raggruppati per campo:

```json
{
  "message": "Validation failed",
  "errors": {
    "alias": ["Alias must contain only lowercase letters (a-z), numbers (0-9), underscores (_), and hyphens (-)"]
  }
}
```

### Errori di limite di frequenza

Le risposte `429` degli endpoint di invio indicano il limite raggiunto e quanto attendere. Vedi [Limiti di frequenza](/it/docs/api-reference/rate-limits/).

```json
{
  "error": "Rate limit exceeded",
  "message": "Too many requests. Maximum 2 messages per second allowed.",
  "limit": 2,
  "current": 2,
  "retry_after": 1
}
```

## Codici di stato HTTP

| Codice | Significato | Cause tipiche nell’API di Emailit |
| --- | --- | --- |
| `200` | OK | La richiesta è riuscita. Invii, aggiornamenti, eliminazioni e letture restituiscono `200`. |
| `201` | Created | È stato creato un dominio, una chiave API, una lista, un iscritto, un contatto, un template, un webhook o un altro oggetto. |
| `202` | Accepted | Il caricamento di un report DMARC è stato accettato per l’elaborazione. |
| `204` | No Content | Un modulo è stato eliminato. La risposta non ha corpo. |
| `400` | Bad Request | JSON non valido, un campo obbligatorio mancante, un valore del tipo sbagliato o fuori intervallo, un `Idempotency-Key` non valido, oppure nessun campo da aggiornare. |
| `401` | Unauthorized | La chiave API manca, non è valida, è stata eliminata o rigenerata, oppure un token OAuth è scaduto. Vedi [Autenticazione](/it/docs/api-reference/authentication/#authentication-errors). |
| `402` | Payment Required | Il workspace non ha crediti sufficienti per l’invio, il nuovo tentativo o la verifica. |
| `403` | Forbidden | Il permesso della chiave non consente l’endpoint, una chiave limitata a un dominio ha inviato da un altro dominio, il workspace è sospeso o non ancora verificato, il dominio di invio è in pausa, oppure la funzione richiede un piano superiore. |
| `404` | Not Found | L’oggetto non esiste in questo workspace, oppure l’alias di un template non ha una versione pubblicata. |
| `409` | Conflict | Esiste già un oggetto con lo stesso nome o la stessa email, oppure è ancora in corso una richiesta con lo stesso `Idempotency-Key`. |
| `413` | Payload Too Large | L’email composta supera i 40 MB, oppure il report DMARC caricato supera i 10 MB. |
| `422` | Unprocessable Entity | La richiesta è valida ma al momento non può essere eseguita: il dominio di `from` non è verificato, un allegato non è stato scaricato, lo stato dell’email non consente l’annullamento o il nuovo tentativo, il suo contenuto è già stato eliminato definitivamente, oppure è stato raggiunto un limite del piano. |
| `429` | Too Many Requests | Il workspace ha raggiunto il limite di invio al secondo o giornaliero, oppure il limite orario degli inoltri. |
| `500` | Internal Server Error | Qualcosa non ha funzionato da parte nostra. Ritenta con backoff e contatta il supporto se il problema persiste. |
| `503` | Service Unavailable | Un’interruzione temporanea di un servizio da cui dipendiamo, come l’archivio delle chiavi di idempotenza o il database di autenticazione. Ritenta con backoff. |

## Errori comuni e come correggerli

| Stato | `error` | Causa | Soluzione |
| --- | --- | --- | --- |
| `400` | `Validation failed` | In un invio mancano `from`, `to`, `subject` o il contenuto, oppure c’è un indirizzo o un allegato non valido. | Correggi ogni voce elencata in `validation_errors`. |
| `400` | `Invalid JSON in request body` (in `message`) | Il corpo non è JSON valido. | Controlla le virgolette e le virgole finali, e invia `Content-Type: application/json`. |
| `400` | `Invalid Idempotency-Key` | La chiave supera i 256 caratteri o contiene caratteri diversi da lettere, cifre, `-` e `_`. | Usa un UUID o un valore sicuro simile. |
| `402` | `Insufficient credits` | I crediti sono esauriti. Ogni destinatario costa un credito. | Acquista crediti o attiva la [ricarica automatica](/it/docs/billing/auto-refill/). |
| `403` | `Workspace not verified` | Il workspace è in modalità sandbox e un destinatario non è un membro del workspace. | Richiedi l’[accesso alla produzione](/it/docs/workspaces/production-access/). |
| `403` | `Domain paused` | L’invio da questo dominio è in pausa a causa della sua [salute degli invii](/it/docs/deliverability/sending-health/). | Risolvi il problema di bounce o di segnalazioni, poi contatta il supporto. |
| `403` | `Domain not authorized` | La chiave API è limitata a un altro dominio di invio. | Invia dal dominio della chiave o usa un’altra chiave. |
| `403` | `plan_required` | La funzione, come i report DMARC o i filtri dei webhook, non è inclusa nel piano. | Passa al piano indicato in `required_plan`. |
| `403` | `mjml_alpha` | La richiesta crea o modifica MJML, oppure chiama un endpoint MJML. MJML è in alpha e aperto solo al team di Emailit. | Usa un altro editor o un altro tipo di contenuto. Vedi [Editor e API MJML](/it/docs/templates/mjml/#who-can-use-mjml). |
| `404` | `Template not found` | L’ID del template non esiste, oppure l’alias non ha una versione pubblicata. | [Pubblica](/it/docs/api-reference/templates/publish/) una versione del template. |
| `409` | `… already exists` | Hai creato un oggetto con un nome o un’email già in uso. | Usa l’oggetto in `existing`, oppure scegli un altro nome. |
| `409` | `Idempotency key in progress` | Un’altra richiesta con la stessa chiave non è ancora terminata. | Attendi un momento e ritenta con la stessa chiave. |
| `413` | `Message too large` | L’email, allegati compresi, supera i 40 MB. | Invia i file di grandi dimensioni come link invece che come allegati. |
| `422` | `Domain not verified` | L’indirizzo `from` non appartiene a un dominio di invio verificato di questo workspace. | [Verifica il dominio](/it/docs/domains/verification/) o cambia `from`. |
| `422` | `Attachment error` | L’`url` di un allegato non è stato scaricato entro 30 secondi, non è raggiungibile o supera i 25 MB. | Controlla che l’URL sia pubblico e il file abbastanza piccolo, oppure invia `content`. |
| `422` | `Cannot cancel email`, `Cannot retry email`, `Cannot update email` | Lo stato dell’email non consente l’azione, mancano meno di 3 minuti all’orario programmato, oppure il contenuto è stato eliminato definitivamente. | Controlla lo `status` dell’email. Le regole sono indicate nella pagina di ogni endpoint. |
| `422` | `Page is too deep` | Hai superato l’offset 2500 di [Elenca gli eventi](/it/docs/api-reference/events/list/). | Restringi i risultati con i filtri `type` o `created_at`. |
| `429` | `Rate limit exceeded`, `Daily limit exceeded` | Il workspace ha raggiunto il limite di invio. | Attendi `retry_after` secondi. Vedi [Limiti di frequenza](/it/docs/api-reference/rate-limits/). |

## Ritenta in sicurezza

- Ritenta le risposte `429`, `500` e `503` dopo un’attesa. Usa l’header `retry-after` quando è presente, altrimenti il backoff esponenziale. [Limiti di frequenza](/it/docs/api-reference/rate-limits/#retry-with-backoff) contiene codice di esempio.
- Non ritentare senza modifiche gli altri errori `4xx`. Continuano a non riuscire allo stesso modo finché non correggi la richiesta.
- Quando ritenti un invio dopo un timeout o un errore `5xx`, riusa lo stesso [`Idempotency-Key`](/it/docs/api-reference/idempotency/), così l’email non viene inviata due volte.

## Vedi anche

  - [Autenticazione](/it/docs/api-reference/authentication/): Credenziali, permessi e tutti gli errori di autenticazione.
  - [Limiti di frequenza](/it/docs/api-reference/rate-limits/): Limiti di invio, header e backoff.
  - [Idempotenza](/it/docs/api-reference/idempotency/): Ritenta gli invii senza inviare due volte.
  - [Log delle richieste](/it/docs/logs/request-logs/): Consulta la richiesta e la risposta di ogni chiamata API non riuscita.

---
Fonte: https://emailit.com/it/docs/api-reference/errors/