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 leesacties opnieuw met begrensde backoff; schrijfacties volgen hun idempotentiecontract. |
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. |
De idempotentiegarantie zorgt ervoor dat overeenkomende nieuwe pogingen binnen drie uur precies één keer worden geaccepteerd. Probeer een schrijfactie opnieuw met dezelfde key en een identiek verzoek, met begrensde backoff. Na een timeout of serverfout is onbekend of het verzoek is geaccepteerd. Een andere key maakt een aparte operatie aan. Als de nieuwe pogingen op zijn of de bewaartermijn is verlopen, behandel je die uitkomst als onopgelost totdat je hem hebt afgestemd.
Stop wanneer het budget voor opnieuw proberen 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 waar dat kan een bekende statusgebaseerde strategie voor opnieuw proberen toe. 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 binnen het idempotentievenster van drie uur dezelfde key en een identiek verzoek.
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.