Een mislukt verzoek kan een vertraging, een gecorrigeerd veld of een andere credential nodig hebben. Het foutantwoord van Bird biedt velden die je handler kan gebruiken om die actie te kiezen.
Welke foutvelden moet je gebruiken?
Gebruik type voor brede afhandeling en code voor een specifiek herstel. Bird plaatst deze velden in een top-level error-object.
Het type groepeert fouten zoals validatie, authenticatie en beperking van het aantal verzoeken. De code identificeert de specifieke fout, zoals E01001 voor veldvalidatie.
Bird hernoemt of hergebruikt nooit een code. Uitgefaseerde codes blijven gereserveerd, dus een bestaande codematch behoudt zijn betekenis.
Toon of log message, maar match niet op de tekst. De formulering kan veranderen zonder dat de fout verandert die je handler moet afhandelen.
De name maakt logs leesbaar. De doc_url linkt naar de documentatie van de code. Log code, name en request_id samen wanneer een operatie mislukt.
Welke fouten moet je opnieuw proberen?
Probeer tijdelijke fouten opnieuw met een begrensde strategie. Los invoer- en credentialproblemen op voordat je het opnieuw probeert. Controleer de specifieke code wanneer één status verschillende acties kan vereisen.
| Antwoord | Standaardactie |
|---|---|
429, E01003 | Wacht op Retry-After en probeer het dan opnieuw. |
500, 502, 503 of 504 | Probeer opnieuw met oplopende vertragingen en een poginglimiet. |
501 | Stop en controleer welke operatie de server ondersteunt. |
401 of 403 | Corrigeer de credential of de bijbehorende rechten voordat je het opnieuw probeert. |
| Veldvalidatie of ongeldige invoer | Corrigeer de velden die het antwoord aanwijst. |
409, E01004 | Wacht tot de lopende operatie klaar is voordat je het opnieuw probeert. |
409, E01005 | Corrigeer het hergebruik van een idempotency-key met andere invoer. |
Gebruik dezelfde idempotency-key wanneer je dezelfde schrijfactie opnieuw probeert. Een timeout of serverfout bewijst niet dat de oorspronkelijke operatie niets heeft gedaan.
Stop wanneer het retrybudget op is en registreer de laatste fout. Een ongewijzigd verzoek onbeperkt herhalen kan een fout verbergen die handmatig ingrijpen vereist.
Hoe ga je om met veldvalidatiefouten?
Lees de details-array op E01001 ValidationError en koppel elke entry aan zijn param. Toon de message van die entry naast het betreffende veld.
Parseer die berichten niet om het veld of de fout te achterhalen. De formulering kan veranderen, net als het top-level-bericht.
Een ongeldig verzoek kan in plaats daarvan E01002 InvalidRequest retourneren. Gebruik het gedocumenteerde herstel in plaats van aan te nemen dat elke invoerfout velddetails bevat.
Kan het antwoord vertellen hoe je kunt herstellen?
Sommige fouten bevatten remediation, een leesbare volgende stap, of next, een geordende lijst van operaties om te proberen.
Toon de herstelsuggestie wanneer die de persoon helpt het probleem te corrigeren. Een autorisatiefout kan bijvoorbeeld een credential met een extra scope vereisen.
Een geautomatiseerde handler kan next gebruiken om een hersteloperatie te kiezen. De handler heeft nog steeds de invoer en rechten van die operatie nodig om hem uit te voeren.
Een vendor_code identificeert een downstreamfout, zoals een SMTP-antwoord of een geweigerde betaling. Raadpleeg de code van die provider wanneer het herstel ervan afhangt.
Wat moet er gebeuren bij een onbekende code?
Houd een standaardbranch die de fout registreert zonder te crashen of onbeperkt opnieuw te proberen. Nieuwe codes en types kunnen verschijnen naarmate de API groeit.
Pas een bekende statusgebaseerde retrystrategie toe waar dat kan. Stop anders en log de code met zijn request-ID voor onderzoek.
De foutengids documenteert het foutantwoord. De foutreferentie vermeldt individuele codes en hun hersteladvies.
Kort gezegd
Match codes, niet berichten.
Bird hernoemt of hergebruikt nooit foutcodes, maar leesbare berichten kunnen veranderen.
Probeer tijdelijke fouten opnieuw met een limiet.
Wacht bij beperking van het aantal verzoeken en verhoog de wachttijd bij tijdelijke serverfouten. Gebruik dezelfde idempotency-key voor een herhaalde schrijfactie.
Lees validatiedetails.
E01001bevat veldproblemen indetails. Gebruik elkeparamom het bijbehorende bericht te koppelen aan het betreffende invoerveld.Houd een fallback voor onbekende fouten.
Log onbekende codes en hun request-ID's zodat nieuwe fouten je handler niet laten crashen.