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 tipo raggruppa gli errori come validazione, autenticazione e limitazione delle richieste. Il codice 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 le letture con intervalli crescenti e un limite di tentativi; le scritture seguono il proprio contratto di idempotenza. |
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. |
La garanzia di idempotenza assicura che i nuovi tentativi corrispondenti vengano accettati esattamente una volta entro tre ore. Riprova una scrittura con la stessa chiave e una richiesta identica, usando un backoff limitato. Dopo un timeout o un errore del server non è noto se la richiesta sia stata accettata. Se cambi chiave, crei un'operazione separata. Quando i nuovi tentativi sono esauriti o il periodo di conservazione è scaduto, considera quell'esito non risolto finché non lo hai riconciliato.
Fermati quando il budget di nuovi tentativi è esaurito e registra l'errore finale. Ripetere all'infinito una richiesta invariata può nascondere un problema che richiede un 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 l'indicazione correttiva quando aiuta la persona a risolvere il problema. Ad esempio, un errore di autorizzazione può richiedere una credenziale con un ambito di autorizzazione 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 tipi possono comparire man mano che API cresce.
Applica una policy nota per i nuovi tentativi 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 progressivamente l'intervallo per gli errori temporanei del server. Mantieni la stessa chiave e una richiesta identica entro la finestra di idempotenza di tre ore.
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.