Una richiesta fallita può richiedere un'attesa, la correzione di un campo o una credenziale diversa. La risposta di errore di Bird fornisce campi che il tuo handler può usare per scegliere l'azione giusta.
Quali campi di errore devo usare?
Usa type per la gestione generale e code per un recupero specifico. Bird inserisce questi campi in un oggetto di primo livello error.
Il type raggruppa gli errori come validazione, autenticazione e limitazione delle richieste. Il code identifica l'errore specifico, ad esempio E01001 per la validazione dei campi.
Bird non rinomina né riutilizza un codice. I codici ritirati restano riservati, quindi un confronto esistente mantiene il suo significato.
Mostra o registra nei log message, ma non confrontarne il testo. La formulazione può cambiare senza che cambi l'errore che il tuo handler deve gestire.
Il name rende i log leggibili. Il doc_url rimanda alla documentazione del codice. Registra nei log code, name e request_id insieme quando un'operazione fallisce.
Quali errori devo riprovare?
Riprova gli errori temporanei con una policy limitata. Correggi i problemi di input e credenziali prima di riprovare. Controlla il codice specifico quando uno stesso status può richiedere azioni diverse.
| Risposta | Azione predefinita |
|---|---|
429, E01003 | Attendi Retry-After, poi riprova. |
500, 502, 503 o 504 | Riprova con intervalli crescenti e un limite di tentativi. |
501 | Fermati e verifica quale operazione supporta il server. |
401 o 403 | Correggi la credenziale o i suoi permessi prima di riprovare. |
| Validazione dei campi o input non valido | Correggi i campi indicati nella risposta. |
409, E01004 | Attendi il completamento dell'operazione in corso prima di riprovare. |
409, E01005 | Correggi il riutilizzo di una chiave di idempotenza con input diverso. |
Mantieni la stessa chiave di idempotenza quando riprovi la stessa scrittura. Un timeout o un errore del server non dimostra che l'operazione originale non abbia avuto effetto.
Fermati quando il budget di tentativi è esaurito e registra l'errore finale. Ripetere una richiesta invariata all'infinito può nascondere un problema che richiede intervento.
Come gestisco gli errori di validazione dei campi?
Leggi l'array details in E01001 ValidationError e associa ogni voce al relativo param. Mostra il message di quella voce accanto al campo interessato.
Non analizzare quei messaggi per identificare il campo o l'errore. La formulazione può cambiare, proprio come il messaggio di primo livello.
Una richiesta malformata può invece restituire E01002 InvalidRequest. Usa il recupero documentato anziché dare per scontato che ogni errore di input contenga dettagli a livello di campo.
La risposta può indicarmi come recuperare?
Alcuni errori includono remediation, un passo successivo leggibile, o next, un elenco ordinato di operazioni da tentare.
Mostra la remediation quando aiuta la persona a correggere il problema. Ad esempio, un errore di autorizzazione può richiedere una credenziale con uno scope aggiuntivo.
Un handler automatizzato può usare next per scegliere un'operazione di recupero. Ha comunque bisogno degli input e dei permessi di quell'operazione prima di eseguirla.
Un vendor_code identifica un errore a valle, come una risposta SMTP o un rifiuto di pagamento. Consulta il codice di quel provider quando il recupero dipende da esso.
Cosa fare con un codice sconosciuto?
Mantieni un ramo predefinito che registra l'errore senza bloccarsi o riprovare all'infinito. Nuovi codici e type possono comparire man mano che API cresce.
Applica una policy di ripetizione basata sullo status quando appropriato. Altrimenti fermati e registra nei log il codice con il relativo ID di richiesta per un'analisi.
La guida agli errori documenta la risposta di errore. Il riferimento errori elenca i singoli codici e le relative indicazioni di recupero.
In breve
Confronta i codici, non i messaggi.
Bird non rinomina né riutilizza i codici di errore, ma i messaggi leggibili possono cambiare.
Riprova gli errori temporanei con un limite.
Attendi in caso di limitazione delle richieste e aumenta l'intervallo per gli errori temporanei del server. Mantieni la stessa chiave di idempotenza per una scrittura ripetuta.
Leggi i dettagli di validazione.
E01001riporta i problemi sui campi indetails. Usa ogniparamper associare il messaggio all'input interessato.Mantieni un fallback per errori sconosciuti.
Registra nei log i codici non riconosciuti e i relativi ID di richiesta, così i nuovi errori non bloccano il tuo handler.