Errori

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:

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

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:

{
  "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, 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:

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

Alcuni errori aggiungono campi che ti aiutano a rimediare:

Errori di convalida dell’invio

Invia un’email e Inoltra un’email controllano l’intero messaggio in una volta e restituiscono tutti i problemi in validation_errors:

{
  "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:

{
  "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.

{
  "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

Errori comuni e come correggerli

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 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, così l’email non viene inviata due volte.

Vedi anche