# Erweiterte Fehlerbehebung Verstehen Sie Fehler auf HTTP-Ebene. Diese Seite behandelt zwei komplexere Themen zum Umgang mit Fehlern: - [HTTP-Antworten, die Fehler darstellen](https://docs.stripe.com/error-low-level.md#errors-in-http) - [Idempotenz und Wiederholungsversuche](https://docs.stripe.com/error-low-level.md#idempotency) Diese Informationen treffen möglicherweise nicht auf Sie zu. Die offiziellen [SDKs](https://docs.stripe.com/sdks.md) von Stripe können die meisten Details zu HTTP und Wiederholungsversuchen handhaben. Wenn Sie eine Client-Bibliothek verwenden, beginnen Sie hier: - [Fehlerbehebung](https://docs.stripe.com/error-handling.md) - [Fehlercodes](https://docs.stripe.com/error-codes.md) ## 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](https://docs.stripe.com/error-handling.md). 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](https://docs.stripe.com/error-low-level.md#content-errors): Ungültiger Inhalt in der API-Anfrage. - [Netzwerkfehler](https://docs.stripe.com/error-low-level.md#network-errors): Zeitweilige Kommunikationsprobleme zwischen Client und Server. - [Serverfehler](https://docs.stripe.com/error-low-level.md#server-errors): Ein Problem auf den Servern von Stripe. Jede Fehlerart erfordert einen anderen Ansatz und eine andere Idempotenz-Semantik. [Eine vollständige Liste der Antwortcodes](https://docs.stripe.com/error-low-level.md#status-codes) 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](https://docs.stripe.com/api/errors.md#errors-code) `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](https://docs.stripe.com/error-codes.md). 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. #### Ruby ```ruby 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](https://docs.stripe.com/webhooks.md) 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. > Behandeln Sie Anfragen, die `500`-Fehler zurückgeben, als unbestimmt. Obwohl Stripe versucht, ihren Teilstatus auf die geeignetste Weise abzugleichen und auch [Webhooks](https://docs.stripe.com/webhooks.md) für neu erstellte Objekte auszulösen, können keine idealen Ergebnisse garantiert werden. 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](https://docs.stripe.com/api/metadata.md) 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](https://stripe.com/blog/idempotency) 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](https://docs.stripe.com/api/idempotent_requests.md) 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](https://docs.stripe.com/api/idempotent_requests.md) 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](https://docs.stripe.com/api/idempotent_requests.md) 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 | | | | | 200 | OK | Alles hat erwartungsgemäß funktioniert. | | 400 | Ungültige Anfrage | Die Anfrage war inakzeptabel, häufig der Fall, wenn ein Pflichtparameter fehlt. | | 401 | Unautorisiert | Es wurde kein gültiger API Schlüssel angegeben. | | 402 | Anfrage fehlgeschlagen | Die Parameter waren gültig, aber die Anfrage ist fehlgeschlagen. | | 403 | Verboten | Der API-Schlüssel hat keine Berechtigungen, um die Anfrage durchzuführen. | | 409 | Konflikt | Die Anfrage steht in Konflikt mit einer anderen Anfrage (möglicherweise aufgrund der Verwendung desselben [Idempotenzschlüssels](https://docs.stripe.com/error-low-level.md#idempotency)). | | 424 | Externe Abhängigkeit fehlgeschlagen | Die Anfrage konnte nicht abgeschlossen werden, da eine Abhängigkeit außerhalb von Stripe fehlerhaft ist. | | 429 | Zu viele Anfragen | Zu viele Anfragen erreichen die API zu schnell. [Wir empfehlen einen exponentiellen Backoff Ihrer Anfragen](https://docs.stripe.com/error-low-level.md#should-retry). | | 500, 502, 503, 504 | Serverfehler | [Auf der Seite von Stripe ist ein Fehler aufgetreten.](https://docs.stripe.com/error-low-level.md#server-errors) |