Erweiterte Fehlerbehebung

Diese Seite behandelt zwei komplexere Themen zum Umgang mit Fehlern:

• HTTP-Antworten, die Fehler darstellen
• Idempotenz und Wiederholungsversuche

Diese Informationen treffen möglicherweise nicht auf Sie zu. Die offiziellen SDKs von Stripe können die meisten Details zu HTTP und Wiederholungsversuchen handhaben. Wenn Sie eine Client-Bibliothek verwenden, beginnen Sie hier:

• Fehlerbehebung
• Fehlercodes

Fehler in HTTP

Auch wenn ein API-Aufruf fehlschlägt, stellen unsere Client-Bibliotheken Fehlerinformationen zur Verfügung, indem sie eine Ausnahme auslösen oder einen Fehlerwert zurückgeben. Wenn Sie jedoch keine Client-Bibliothek verwenden oder eine ungewöhnliche Situation eintritt, benötigen Sie möglicherweise einfache Details zu HTTP-Antworten und wann wir diese ausgeben.

Aus Sicht von HTTP lassen Fehler sich in drei Hauptkategorien unterteilen:

• Inhaltsfehler: Ungültiger Inhalt in der API-Anfrage.
• Netzwerkfehler: Zeitweilige Kommunikationsprobleme zwischen Client und Server.
• Serverfehler: Ein Problem auf den Servern von Stripe.

Jede Fehlerart erfordert einen anderen Ansatz und eine andere Idempotenz-Semantik. Eine vollständige Liste der Antwortcodes und ihrer Bedeutung finden Sie am Ende dieser Seite.

Inhaltsfehler

Inhaltsfehler sind das Ergebnis davon, dass der Inhalt einer API-Anfrage ungültig ist und eine HTTP-Antwort mit einem Antwortcode 4xx zurückgibt. Die API-Server könnten z. B. einen 401-Fehler zurückgeben, wenn Sie einen ungültige API-Schlüssel angegeben haben, oder einen 400-Fehler, wenn ein erforderlicher Parameter fehlte. Integrationen sollten die ursprüngliche Anfrage korrigieren und es erneut versuchen. Je nach Art des Benutzerfehlers (beispielsweise eine abgelehnte Karte) kann es möglich sein, das Problem programmatisch zu handhaben. Fügen Sie in diesen Fällen ein code-Feld ein, damit eine Integration angemessen reagieren kann. Weitere Details finden Sie unter Fehlercodes.

Bei einer POST-Operation mit einem Idempotenz-Schlüssel werden die API-Server von Stripe die Ergebnisse der Anfrage zwischenspeichern, solange eine API-Methode mit der Ausführung begonnen hat, unabhängig davon, was sie waren. Eine Anfrage, die einen 400-Fehler zurückgibt, sendet denselben 400-Fehler zurück, wenn eine neue Anfrage mit demselben Idempotenz-Schlüssel folgt. Generieren Sie einen neuen Idempotenz-Schlüssel, wenn Sie die ursprüngliche Anfrage ändern, um ein erfolgreiches Ergebnis zu erhalten. Diese Operation enthält einige Vorbehalte. Zum Beispiel kann eine Anfrage, die mit einem 429-Fehler ratenbegrenzt ist, ein anderes Ergebnis mit demselben Idempotenz-Schlüssel erzeugen, da Ratenbegrenzer vor der Idempotenz-Schicht der API laufen. Das Gleiche gilt für 401-Fehler, bei denen ein API-Schlüssel ausgelassen wurde, oder die meisten 400-Fehler, bei denen ungültige Parameter gesendet wurden. Trotzdem ist die sicherste Strategie bei 4xx-Fehlern, immer einen neuen Idempotenz-Schlüssel zu erzeugen.

Netzwerkfehler

Netzwerkfehler sind die Folge von Konnektivitätsproblemen zwischen Client und Server. Sie geben einfache Fehler wie Socket- oder Timeout-Ausnahmen zurück. Beispielsweise kann auf einem Client beim Versuch auf den Stripe-Server zuzugreifen, eine Zeitüberschreitung auftreten. Oder eine API-Antwort wird nicht empfangen, weil die Verbindung vorzeitig beendet wird. Obwohl ein Netzwerkfehler nach dem Beheben der Verbindungsprobleme als behoben erscheinen kann, verbirgt sich manchmal eine andere Art von Fehler hinter dem zeitweiligen Problem.

Bei dieser Fehlerklasse ist der Wert von Idempotenz-Schlüsseln und Anforderungswiederholungen am offensichtlichsten. Wenn sporadische Probleme auftreten, werden die Clients normalerweise in einem Zustand gelassen, in dem sie nicht wissen, ob der Server die Anfrage erhalten hat oder nicht. Um eine definitive Antwort zu erhalten, sollten sie solche Anfragen mit denselben Idempotenz-Schlüsseln und denselben Parametern so lange wiederholen, bis sie in der Lage sind, ein Ergebnis vom Server zu erhalten. Das Senden derselben Idempotenz mit anderen Parametern erzeugt einen Fehler, der anzeigt, dass die neue Anfrage nicht mit der ursprünglichen übereinstimmt.

Die meisten Clientbibliotheken können automatisch Idempotenz-Schlüssel und Wiederholungsanfragen generieren, müssen aber entsprechend konfiguriert werden. Sie führen den ersten Wiederholungsversuch schnell nach dem ersten Fehler durch und die nachfolgenden Wiederholungsversuche nach einem exponentiellen Backoff-Zeitplan, wobei davon ausgegangen wird, dass ein einzelner Fehler oft ein zufälliges Ereignis ist, aber ein Muster von wiederholten Fehlern wahrscheinlich ein dauerhaftes Problem darstellt.

Stripe.max_network_retries = 2

Server

Serverfehler sind das Ergebnis eines Problems mit den Stripe-Servern und geben eine HTTP-Antwort mit einem 5xx-Fehlercode zurück. Diese Fehler sind am schwierigsten zu handhaben und wir arbeiten daran, dass sie so selten wie möglich auftreten. Gute Integrationen sind in der Lage, mit ihnen umzugehen, wenn sie trotzdem auftreten.

Wie bei Nutzerfehlern speichert die Idempotenz-Schicht das Ergebnis von POST-Mutationen, die zu Serverfehlern führen (insbesondere 500-Fehler, die interne Serverfehler sind), sodass ein erneuter Versuch mit demselben Idempotenz-Schlüssel normalerweise das gleiche Ergebnis liefert. Der Client kann die Anfrage mit einem neuen Idempotenz-Schlüssel erneut versuchen, aber wir raten davon ab, da der ursprüngliche Schlüssel möglicherweise Nebeneffekte erzeugt hat.

Das Ergebnis einer 500-Anfrage sollten Sie als unbestimmt betrachten. Der wahrscheinlichste Zeitpunkt für die Beobachtung ist während eines Produktionsvorfalls und im Allgemeinen während der Behebung eines solchen Vorfalls. Die Entwickler/innen von Stripe untersuchen fehlgeschlagene Anfragen und versuchen, die Ergebnisse von Mutationen, die zu 500-Anfragen führen, entsprechend abzugleichen. Während sich die im Idempotenz-Cache gespeicherte Antwort auf diese Anfragen nicht ändert, werden wir versuchen, Webhooks für alle neuen Objekte auszulösen, die im Rahmen des Abgleichs von Stripe erstellt werden. Die genaue Art der rückwirkenden Änderungen im System hängt stark von der Art der Anforderung ab. Wenn beispielsweise beim Erstellen einer Lastschrift der Fehler 500 angezeigt wird, wir aber feststellen, dass die Informationen an ein Zahlungsnetzwerk gesendet wurden, versuchen wir, die Lastschrift vorzuziehen. Wenn nicht, versuchen wir, sie zurückzunehmen. Wenn das Problem dadurch nicht behoben wird, werden möglicherweise weiterhin Anfragen mit einem 500-Fehler angezeigt, die für den/die Nutzer/in sichtbare Nebeneffekte haben.

Damit Ihre Integration den größtmöglichen 500-Bereich handhaben kann, müssen Sie Webhook-Handler konfigurieren, die in der Lage sind, Ereignisobjekte zu empfangen, die Sie in normalen API-Antworten nie empfangen. Eine Technik für den Querverweis dieser neuen Objekte mit den Daten aus dem lokalen Status einer Integration besteht darin, beim Erstellen neuer Ressourcen mit der API einen lokalen Bezeichner mit den Metadaten zu senden. Dieser Bezeichner erscheint im Metadatenfeld eines Objekts, das über einen Webhook ausgegeben wird, auch wenn der Webhook später als Teil der Abstimmung erzeugt wird.

Idempotenz

Idempotenz ist ein Web-API-Designprinzip, das als die Fähigkeit definiert ist, den gleichen Vorgang mehrmals durchzuführen, ohne das Ergebnis über den ersten Versuch hinaus zu ändern. Dadurch können API-Anfragen in einigen Situationen sicher wiederholt werden – insbesondere, wenn die erste Anfrage aufgrund eines Netzwerkfehlers nicht beantwortet wird. Da mit einer gewissen Häufigkeit von zeitweiligen Ausfällen zu rechnen ist, benötigen Clients eine Möglichkeit, fehlgeschlagene Anfragen mit einem Server abzugleichen. Idempotenz bietet dafür einen Mechanismus.

Die meisten Clientbibliotheken können Idempotenz-Schlüssel und Wiederholungsanfragen automatisch generieren, diese Vorgehensweise müssen Sie jedoch konfigurieren. Generieren Sie Idempotenz-Schlüssel und erstellen Sie Ihre eigene Logik für Wiederholungsversuche, um eine detailliertere Kontrolle über die Wiederholungsversuche zu erhalten.

GET- und DELETE-Anfragen

Die Stripe-API garantiert die Idempotenz von GET- und DELETE-Anfragen, sodass sie immer gefahrlos wiederholt werden können.

POST-Anfragen

Durch Einfügen eines Idempotenz-Schlüssels werden POST-Anfragen idempotent, was die API veranlasst, die erforderlichen Aufzeichnungen durchzuführen, um doppelte Vorgänge zu vermeiden. Clients können Anforderungen, die einen Idempotenz-Schlüssel enthalten, bedenkenlos wiederholen, solange die zweite Anforderung innerhalb von 24 Stunden nach Erhalt des Schlüssels erfolgt (Schlüssel verfallen aus dem System nach 24 Stunden). Wenn beispielsweise eine Anfrage zum Erstellen eines Objekts aufgrund eines Netzwerkverbindungsfehlers nicht reagiert, kann ein Client die Anfrage mit demselben Idempotenz-Schlüssel wiederholen, um zu garantieren, dass nicht mehr als ein Objekt erstellt wird.

Senden von Idempotenz-Schlüsseln

Idempotenz-Schlüssel werden im Idempotency-Key-Header gesendet. Verwenden Sie sie für alle POST-Anfragen an die Stripe-API. Die meisten offiziellen Client-Bibliotheken können sie automatisch senden, solange sie für das Senden von Wiederholungen konfiguriert sind.

Wenn Sie sich entscheiden, Idempotenz-Schlüssel manuell zu senden zu senden, stellen Sie sicher, dass die verwendeten Token eindeutig genug sind, um eine einzelne Operation innerhalb Ihres Kontos über mindestens die letzten 24 Stunden eindeutig zu identifizieren. Es gibt zwei gängige Strategien zur Erzeugung von Idempotenz-Schlüsseln:

• Die Verwendung eines Algorithmus, der einen Token mit ausreichender Zufälligkeit erzeugt, z. B. UUID v4.
• Ableitung des Schlüssels von einem vom Nutzer/von der Nutzerin angehängten Objekt, z. B. der ID eines Warenkorbs. Dies bietet eine relativ unkomplizierte Möglichkeit, sich vor doppelten Übertragungen zu schützen.

Sie können eine zuvor ausgeführte Antwort, die vom Server wiedergegeben wird, anhand des Headers Idempotent-Replayed: true erkennen.

Der Stripe-Should-Retry-Header

Über eine Kundenbliothek kann nicht immer mit Sicherheit festgestellt werden, ob die Anfrage allein aufgrund des Statuscodes oder des Inhalts im Antworttext wiederholt werden sollte. Die API antwortet mit dem Header Stripe-Should-Retry, wenn zusätzliche Informationen darüber vorliegen, dass die Anfrage wiederholt werden kann.

• Wenn Stripe-Should-Retry auf true festgelegt ist, zeigt dies an, dass ein Client die Anfrage wiederholen sollte. Clients sollten trotzdem eine gewisse Zeit warten (wahrscheinlich nach einem exponentiellen Backoff-Zeitplan vorgegeben), bevor sie die nächste Anfrage stellen, um die API nicht zu überlasten.
• Wenn Stripe-Should-Retry auf false festgelegt ist, bedeutet dies, dass ein Client die Anfrage nicht wiederholen sollte, da dies keinen zusätzlichen Effekt haben wird.
• Wenn Stripe-Should-Retry in der Antwort nicht festgelegt ist, bedeutet dies, dass die API nicht feststellen kann, ob sie die Anfrage wiederholen kann oder nicht. Clients sollten auf andere Eigenschaften der Antwort (wie den Statuscode) zurückgreifen, um eine Entscheidung zu treffen.

Die in den Client-Bibliotheken von Stripe integrierten Wiederholungsmechanismen berücksichtigen Stripe-Should-Retry automatisch. Wenn Sie eine dieser Bibliotheken verwenden, müssen Sie dies also nicht manuell durchführen.

HTTP Status -Referenz