Errori
Mailbeam usa codici di stato HTTP standard. Tutte le risposte di errore includono un campo error leggibile dalla macchina e un message leggibile dalle persone.
Struttura di una risposta di errore
{
"error": "invalid_email_format",
"message": "The email address is not RFC 5322 compliant.",
"request_id": "req_01hx9abc123"
}
Nel tuo codice controlla sempre il campo error: message può cambiare, error è stabile.
Codici di stato HTTP
| Codice | Significato |
|---|
200 | La richiesta è andata a buon fine |
400 | Richiesta errata: controlla il corpo |
401 | L'autenticazione è fallita |
403 | Vietato: permessi insufficienti |
422 | Errore di validazione: l'indirizzo ha un problema preciso |
413 | Il corpo della richiesta è troppo grande |
429 | Limite di ritmo o quota superati |
500 | Errore interno del server: contatta l'assistenza |
503 | Capacità non disponibile in questa pubblicazione |
Codici di errore
Errori di autenticazione
| Errore | Stato | Descrizione |
|---|
missing_api_key | 401 | Non c'è l'intestazione Authorization |
invalid_api_key | 401 | Il formato della chiave non è valido |
revoked_api_key | 401 | La chiave è stata revocata |
insufficient_permissions | 403 | La chiave non ha l'ambito necessario |
Errori di validazione
| Errore | Stato | Descrizione |
|---|
invalid_email_format | 422 | L'email non rispetta la sintassi dell'RFC 5322 |
email_too_long | 422 | L'email supera i 254 caratteri |
missing_required_field | 400 | Manca un campo obbligatorio nel corpo |
invalid_json | 400 | Il corpo della richiesta non è JSON valido |
invalid_request | 400 | Il JSON è ben formato ma non è valido: per esempio un URL di webhook che non è HTTPS |
payload_too_large | 413 | Il corpo supera il limite di dimensione di quell'endpoint |
Errori di limite di ritmo
| Errore | Stato | Descrizione |
|---|
rate_limit_exceeded | 429 | Limite al secondo raggiunto; guarda retry_after |
quota_exceeded | 429 | Quota mensile esaurita (il piano Free blocca; quelli a pagamento proseguono con fatturazione per eccedenza) |
Errori del server
| Errore | Stato | Descrizione |
|---|
internal_error | 500 | Errore transitorio del server: riprova con rallentamento |
service_unavailable | 503 | Una capacità non è configurata in questa pubblicazione |
upstream_timeout | 504 | Il sondaggio SMTP ha esaurito il tempo; il risultato non è conclusivo |
Gestire gli errori nel tuo codice
try {
const result = await verifyEmail(email);
if (!result.valid) {
// L'email non è valida ma la richiesta è andata bene: questo NON è un errore
handleInvalidEmail(result.reason);
}
} catch (err) {
switch (err.code) {
case "rate_limit_exceeded":
await sleep(err.retryAfter * 1000);
// riprova
break;
case "quota_exceeded":
// Avvisa chi tiene i sistemi, usa un piano B oppure lascia passare la registrazione
notifyOpsTeam();
break;
case "invalid_api_key":
case "revoked_api_key":
// Allerta: è un problema di configurazione
alertPagerDuty("chiave API di Mailbeam non valida");
break;
default:
// Registra e prosegui: non bloccare gli utenti per errori imprevisti
logger.error("Errore di Mailbeam", { code: err.code, requestId: err.requestId });
}
}
Il campo reason
Quando valid è false, il campo reason contiene una stringa leggibile dalla macchina che spiega perché:
| Motivo | Spiegazione |
|---|
invalid_syntax | Non supera il controllo di formato dell'RFC 5322 |
no_mx_records | Il dominio non ha server di posta, oppure pubblica un MX nullo |
domain_not_found | Il dominio non si risolve affatto |
smtp_rejected | La casella non esiste |
mailbox_full | La casella esiste ma ha superato la sua quota |
disposable_domain | Combacia con un fornitore di posta temporanea |
role_address | Sembra un indirizzo non personale |
catch_all_unverifiable | Il dominio accetta tutta la posta; l'SMTP non è conclusivo |
greylisted | Il server ci ha chiesto di tornare più tardi: trattalo come sconosciuto |
smtp_blocked | Il server ha rifiutato il nostro sondaggio, non l'indirizzo |
smtp_unreachable | Nessun server di posta ha risposto |
timeout | Il sondaggio ha esaurito il tempo: trattalo come sconosciuto |
status contro valid
valid è un booleano, e con due stati non si può distinguere «questa casella non
esiste» da «non siamo riusciti a saperlo». Usa status quando quella differenza
conta:
| Stato | Significato | valid |
|---|
deliverable | La casella è stata confermata | true |
undeliverable | Confermato come cattivo: sintassi errata, nessuna via per la posta, casella rifiutata, usa e getta | false |
risky | Reale ma di bassa qualità: dominio catch-all, indirizzo di ruolo, casella piena | false |
unknown | Non siamo riusciti a saperlo: greylisting, sondaggio bloccato, DNS scaduto | false |
Bloccare le registrazioni per undeliverable è sicuro. Bloccare per unknown
blocca utenti veri: usa invece lo score.
Non bloccare mai un utente solo per catch_all_unverifiable. Usa il campo score per prendere decisioni con sfumature.