Errori

Ogni richiesta Bird API fallita restituisce la stessa risposta di errore JSON, annidata sotto una chiave di primo livello error. Questa è una risposta reale a una richiesta di invio con corpo vuoto:

Esempio di codice

{
  "error": {
    "type": "validation_error",
    "code": "E01001",
    "name": "ValidationError",
    "message": "Request has 1 validation error.",
    "doc_url": "https://bird.com/docs/api/errors/E01001",
    "request_id": "req_01ky7q3hckecgv6d7jpq865532",
    "details": [{ "param": "body", "message": "missing properties 'from', 'to'" }]
  }
}

Lo status HTTP deriva dal type. Gli errori client usano 400 per richieste malformate, 401 o 403 per errori di accesso, 402 per la fatturazione e 404 per risorse mancanti. Usano 409 per i conflitti, 412 per precondizioni non soddisfatte, 422 per errori di validazione e regole di business e 429 per la limitazione delle richieste. Gli errori lato Bird usano 5xx. Lo status identifica la categoria; la risposta di errore spiega cosa è successo.

I campi della risposta di errore

Campo	Ruolo
type	Categoria generale per la gestione approssimativa: validation_error, auth_error, permission_error, not_found_error, conflict_error, rate_limit_error, billing_error, internal_error e pochi altri. Un enum chiuso che cresce raramente.
code	Identificatore opaco e stabile (E01001). Il riferimento canonico: univoco, mai rinominato, mai riutilizzato. Quando un errore viene ritirato, il suo codice resta riservato permanentemente.
name	Slug leggibile (ValidationError) per la leggibilità dei log. Sempre accompagnato da code, mai un sostituto.
message	Descrizione leggibile. Non stabile: il testo può cambiare senza preavviso. Visualizzalo, registralo nei log, non analizzarlo mai.
param	Per gli errori relativi all'input, il campo che ha causato il problema. Omesso quando non applicabile.
doc_url	Link stabile alla pagina della documentazione per questo codice.
request_id	Sempre presente, e restituito anche come header di risposta X-Request-Id. Citalo nelle richieste di supporto: permette a Bird di tracciare la richiesta esatta.
details	Problemi di validazione per campo. Presente solo nelle risposte validation_error.
remediation	Un passo successivo leggibile per risolvere l'errore. Presente quando è nota una modalità di recupero.
next	Operazioni che risolvono l'errore, nell'ordine in cui provarle. Presente per errori con un percorso di recupero ben definito, come le precondizioni non soddisfatte.
vendor_code	Codice verbatim da un sistema a valle (un codice di risposta SMTP, un codice di rifiuto di pagamento). Presente solo quando Bird espone il codice di un sistema esterno su cui potresti voler agire.

Usa type per la gestione approssimativa e code per la gestione specifica, mai message. Un client tipico fa switch su type (riprovare su rate_limit_error, mostrare validation_error all'utente, allertare qualcuno su internal_error) e confronta singoli valori code solo per i pochi errori che gestisce in modo specifico.

Codici come E04012 sono volutamente opachi. Ogni codice rimanda a una pagina di documentazione tramite doc_url, che spiega la causa e come risolvere. Il catalogo completo si trova nel riferimento errori.

Errori di validazione: un codice, molti dettagli

La validazione a livello di campo non prevede un codice separato per ogni combinazione campo-errore. Ogni errore di validazione è E01001 ValidationError con un array details che elenca ogni problema a livello di campo come {param, message}, così come l'errore di invio catturato elenca le proprietà mancanti. Le stringhe message dentro details possono cambiare e vanno solo visualizzate. Usa param per mappare i problemi ai campi del form.

Indicazioni per il recupero: rimedio e passi successivi

Gli errori con una correzione nota la includono nella risposta di errore. Questa è una risposta reale a una chiamata webhooks effettuata con una chiave API priva dello scope richiesto:

Esempio di codice

{
  "error": {
    "type": "permission_error",
    "code": "E02035",
    "name": "InsufficientScope",
    "message": "This request requires the \"webhooks:read\" scope, which your credential has not been granted.",
    "param": "webhooks:read",
    "doc_url": "https://bird.com/docs/api/errors/E02035",
    "request_id": "req_01ky7q4665emc9tw1pxkptaqwq",
    "remediation": "Re-authenticate with a credential that has been granted the required scope, then retry."
  }
}

remediation è una frase destinata a un essere umano o al log di un agente; next, quando presente, elenca le operazioni API che risolvono l'errore nell'ordine in cui provarle (verificare un dominio, poi riprovare l'invio). Agenti e CLI possono eseguire next direttamente; i client interattivi possono mostrare remediation così com'è.

Gestire bene gli errori

Riprova 429 e 5xx, nient'altro per default. Rispetta Retry-After sulla limitazione delle richieste (vedi Limitazione delle richieste), usa il backoff esponenziale su 5xx e invia un Idempotency-Key per rendere sicuri i retry delle richieste mutanti.
Registra code, name e request_id insieme. Il codice è ciò che cercherai nella documentazione e nei tuoi log; il request ID è ciò di cui ha bisogno il supporto.
Tollera nuovi codici e tipi. Nuovi codici di errore vengono rilasciati regolarmente con la crescita dei prodotti e l'enum type occasionalmente acquisisce un valore. Scrivi il tuo handler con un branch di default ragionevole anziché un match esaustivo.

Passi successivi

Riferimento errori: il catalogo completo degli errori, una pagina per codice
Idempotenza: retry sicuri per le richieste mutanti
Limitazione delle richieste: header dei limiti e indicazioni sul backoff

Risorse correlate

Prosegui con la documentazione, le guide e gli esempi per questo argomento. Le risorse sono in inglese.

Comprendi il concettoShould I use a Bird SDK or call the API directly?Segui il percorso di apprendimentoBuild your first integration Guida all'implementazioneSend your first email

Ottieni un brief di implementazione