Erkennen und reagieren Sie auf Ablehnungen, ungültige Daten, Netzwerkprobleme und mehr.
Stripe bietet viele Arten von Fehlern. Sie können externe Ereignisse wie abgelehnte Zahlungen und Netzwerkunterbrechungen oder Code-Probleme wie ungültige API-Aufrufe widerspiegeln.
Verwenden Sie für den Umgang mit Fehlern einige oder alle Techniken in der folgenden Tabelle. Unabhängig von der verwendeten Technik können Sie mit unseren empfohlenen Antworten für jeden Fehlertyp weitermachen.
Untersuchen Sie frühere Probleme und unterstützen Sie andere Techniken
Manchmal
Ausnahmen abfangen
Wenn ein unmittelbares Problem das Fortsetzen eines API-Aufrufs verhindert, löst die Ruby-Bibliothek von Stripe eine Ausnahme aus. Dies ist eine bewährte Methode, Ausnahmen abzufangen und zu handhaben.
Verwenden Sie das Ruby-Schlüsselwort rescue, um eine Ausnahme abzufangen. Fangen Sie Stripe::StripeError oder seine Unterklassen ab, um nur Stripe-spezifische Ausnahmen zu handhaben. Jede Unterklasse stellt eine andere Art von Ausnahme dar. Wenn Sie eine Ausnahme abfangen, können Sie anhand ihrer Klasse eine Antwort auswählen.
defexample_function(params)beginStripe::PaymentIntent.create(params)rescueStripe::CardError=> e
puts "A payment error occurred: #{e.error.message}"rescueStripe::InvalidRequestError=> e
puts "An invalid request occurred."rescueStripe::StripeError=> e
puts "Another problem occurred, maybe unrelated to Stripe."else
puts "No error."endend
Nachdem Sie den Umgang mit Ausnahmen eingerichtet haben, testen Sie diese mit verschiedenen Daten, einschließlich Testkarten, um unterschiedliche Zahlungsergebnisse zu simulieren.
Stripe benachrichtigt Sie mithilfe von Webhooks über viele Problemtypen. Dazu gehören Probleme, die nicht unmittelbar auf einen API-Aufruf folgen. Zum Beispiel:
Sie verlieren eine Anfechtung.
Eine wiederkehrende Zahlung schlägt fehl, nachdem sie monatelang erfolgreich war.
Ihr Frontend bestätigt eine Zahlung, geht aber offline, bevor es feststellt, dass die Zahlung fehlgeschlagen ist. (Das Backend empfängt weiterhin eine Webhook-Benachrichtigung, obwohl es den API-Aufruf nicht getätigt hat.)
Sie müssen nicht jeden Webhook-Ereignistyp bearbeiten. Einige Integrationen handhaben gar keine.
Beginnen Sie in Ihrem Webhook-Handler mit den Grundschritten aus dem Webhook-Builder: Rufen Sie ein Ereignisobjekt ab und finden Sie mithilfe des Ereignistyps heraus, was passiert ist. Wenn der Ereignistyp dann auf einen Fehler hinweist, führen Sie diese zusätzlichen Schritte aus:
Greifen Sie auf event.data.object zu, um das betreffende Objekt abzurufen.
require'stripe'require'sinatra'
post '/webhook'do
payload = request.body.read
data =JSON.parse(payload, symbolize_names:true)# Get the event object
event =Stripe::Event.construct_from(data)# Use the event type to find out what happenedcase event.type
when'payment_intent.payment_failed'# Get the object affected
payment_intent = event.data.object
# Use stored information to get an error object
e = payment_intent.last_payment_error
# Use its type to choose a responsecase e.type
when'card_error'
puts "A payment error occurred: #{e.message}"when'invalid_request'
puts "An invalid request occurred."else
puts "Another problem occurred, maybe unrelated to Stripe."endend
content_type 'application/json'{
status:'success'}.to_json
end
Um zu testen, wie Ihre Integration auf Webhook-Ereignisse reagiert, können Sie Webhook-Ereignisse lokal auslösen. Nachdem Sie die Einrichtungsschritte unter diesem Link abgeschlossen haben, lösen Sie eine fehlgeschlagene Zahlung aus, um die entsprechende Fehlermeldung anzuzeigen.
Command Line
stripe trigger payment_intent.payment_failed
Output
A payment error occurred: Your card was declined.
Gespeicherte Informationen zu Fehlern erhalten
In vielen Objekten werden Informationen zu Fehlern gespeichert. Wenn also bereits ein Fehler aufgetreten ist, können Sie das Objekt abrufen und untersuchen, um mehr zu erfahren. In vielen Fällen liegen gespeicherte Informationen in Form eines Fehlerobjekts vor, und Sie können seinen Typ verwenden, um eine Antwort auszuwählen.
Zum Beispiel:
Rufen Sie einen bestimmten Payment Intent ab.
Überprüfen Sie, ob ein Zahlungsfehler aufgetreten ist, indem Sie feststellen, ob last_payment_error leer ist.
Falls dies der Fall ist, protokollieren Sie den Fehler, einschließlich seines Typs und des betroffenen Objekts.
Um Code zu testen, der gespeicherte Informationen zu Fehlern verwendet, müssen Sie häufig fehlgeschlagene Transaktionen simulieren. Dies geht häufig mithilfe von Testkarten oder Testbanknummern. Beispiel:
In der Stripe Ruby-Bibliothek gehören Fehlerobjekte zu stripe.error.StripeError und seinen Unterklassen. Verwenden Sie die Dokumentation für jede Klasse, um Tipps für Antworten zu erhalten.
Sie haben einen Idempotenz-Schlüssel für ein unerwartetes Ereignis verwendet, wie das Wiederholen einer Anfrage, jedoch mit Übergabe unterschiedlicher Parameter.
Sie verwenden die Signaturverifizierung von Webhooks und konnten die Authentizität eines Webhook-Ereignisses nicht bestätigen.
Zahlungsfehler
Zahlungsfehler – aus historischen Gründen auch manchmal als „Kartenfehler“ bezeichnet – decken ein breites Spektrum geläufiger Probleme ab. Sie sind auf drei Kategorien verteilt:
Radar, das Betrugspräventionssystem von Stripe, hat die Zahlung blockiert
Lösungen
Dieser Fehler kann auftreten, wenn Ihre Integration ordnungsgemäß funktioniert. Fangen Sie ihn ab und fordern Sie den Kunden/die Kundin auf, eine andere Zahlungsmethode zu wählen.
Probieren Sie Folgendes, damit weniger legitime Zahlungen blockiert werden:
Dieser Fehler kann auftreten, obwohl Ihre Integration korrekt funktioniert. Er weist auf eine Aktion des Kartenausstellers hin, die legitim sein kann. Verwenden Sie den Ablehnungscode, um die nächsten angemessenen Schritte zu ermitteln. Entsprechende Antworten auf jeden Code finden Sie in der Dokumentation zu Ablehnungscodes.
Dieser Fehler kann auftreten, obwohl Ihre Integration korrekt funktioniert. Verwenden Sie den Fehlercode, um die nächsten angemessenen Schritte zu ermitteln. Entsprechende Antworten auf jeden Code finden Sie in der Dokumentation zu Fehlercodes.
Ungültige Anfragefehler
Typ
Stripe::InvalidRequestError
Problem
Sie haben einen API-Aufruf mit den falschen Parametern, im falschen Status oder auf ungültige Weise ausgeführt.
Lösungen
In den meisten Fällen liegt das Problem bei der Anfrage selbst. Entweder sind seine Parameter ungültig oder sie kann im aktuellen Status Ihrer Integration nicht ausgeführt werden.
Unter dem Link erhalten Sie schnellen Zugriff auf Dokumentation zum Fehlercode.
Wenn der Fehler einen bestimmten Parameter beinhaltet, verwenden Sie , um diesen zu bestimmen.
Verbindungsfehler
Typ
Stripe::APIConnectionError
Problem
Zwischen Ihrem Server und Stripe ist ein Netzwerkproblem aufgetreten.
Lösungen
Behandeln Sie das Ergebnis des API-Aufrufs als unbestimmt. Das heißt, gehen Sie weder davon aus, dass es erfolgreich war, noch dass es fehlgeschlagen ist.
So finden Sie heraus, ob es erfolgreich war:
Rufen Sie das entsprechende Objekt von Stripe ab und prüfen Sie seinen Status.
Überwachen Sie die Webhook-Benachrichtigung, ob der Vorgang erfolgreich war oder fehlgeschlagen ist.
So vereinfachen Sie den Wiederherstellungsprozess nach Verbindungsfehlern:
Verwenden Sie beim Erstellen oder Aktualisieren eines Objekts einen Idempotenz-Schlüssel. Falls ein Verbindungsfehler auftritt, können Sie die Anfrage dann sicher wiederholen, ohne dass das Risiko besteht, dass ein zweites Objekt erstellt wird oder dass die Aktualisierung zweimal durchgeführt wird. Wiederholen Sie die Anfrage mit demselben Idempotenz-Schlüssel, bis Sie eine eindeutige Erfolgs- oder Fehlermeldung erhalten. Weitere Hinweise zu dieser Strategie finden Sie unter Low-Level-Fehler beheben.
Aktivieren Sie automatische Wiederholungsversuche.. Anschließend generiert Stripe Idempotenz-Schlüssel und wiederholt Anfragen für Sie, wenn dies sicher durchgeführt werden kann.
Dieser Fehler kann andere verbergen. Es ist möglich, dass ein anderer Fehler zum Vorschein tritt, sobald der Verbindungsfehler behoben wurde. Durchsuchen Sie all diese Lösungen nach Fehlern, genau wie in der ursprünglichen Anfrage.
API-Fehler
Typ
Stripe::APIError
Problem
Auf der Seite von Stripe ist ein Fehler aufgetreten. (Dies kommt sehr selten vor).
Lösungen
Behandeln Sie das Ergebnis des API-Aufrufs als unbestimmt. Das heißt, gehen Sie weder davon aus, dass es erfolgreich war, noch dass es fehlgeschlagen ist.
Über Webhooks erhalten Sie Informationen zu dem Ergebnis. Nach Möglichkeit löst Stripe Webhooks für alle neuen Objekte aus, die wir erstellen, während wir an der Lösung für ein Problem arbeiten.
Sie haben einen Idempotenz-Schlüssel für ein unerwartetes Ereignis verwendet, wie das Wiederholen einer Anfrage, jedoch mit Übergabe unterschiedlicher Parameter.
Lösungen
Nach Verwenden eines Idempotenz-Schlüssels kann dieser nur für identische API-Aufrufe wiederverwendet werden.
Verwenden Sie Idempotenzschlüssel unter 255 Zeichen.
Berechtigungsfehler
Typ
Stripe::PermissionError
Problem
Der für diese Anfrage verwendete API-Schlüssel verfügt nicht über die erforderlichen Berechtigungen.
Führen Sie eine Aktion im Dashboard durch, während Sie als Nutzerrolle ohne Berechtigung angemeldet sind?
Ratenbegrenzungsfehler
Typ
Stripe::RateLimitError
Problem
Sie haben in zu kurzer Zeit zu viele API-Aufrufe getätigt.
Lösungen
Wenn ein einzelner API-Aufruf diesen Fehler auslöst, warten Sie und versuchen Sie es erneut.
Um die Ratenbegrenzung automatisch zu handhaben, wiederholen Sie den API-Aufruf nach einer Verzögerung und erhöhen Sie diese exponentiell, wenn der Fehler weiterhin auftritt. Weitere Hinweise finden Sie in der Dokumentation zu Ratenbegrenzungen.
Wenn Sie mit einem starken Anstieg des Datenverkehrs rechnen und eine Erhöhung der Ratenbegrenzung anfordern möchten, kontaktieren Sie den Support im Voraus.
Fehler beim Verifizieren der Signatur
Typ
Stripe::SignatureVerificationError
Problem
Sie verwenden die Signaturverifizierung von Webhooks und konnten die Authentizität eines Webhook-Ereignisses nicht bestätigen.
Lösungen
Dieser Fehler kann auftreten, wenn Ihre Integration ordnungsgemäß funktioniert. Wenn Sie die Webhook-Signaturverifizierung verwenden und Dritte versuchen, Ihnen einen gefälschten oder böswilligen Webhook zu senden, schlägt die Verifizierung fehl und resultiert in diesem Fehler. Fangen Sie ihn ab und antworten Sie mit dem Statuscode 400 Bad Request.
Wenn Sie diese Fehlermeldung erhalten, obwohl dies nicht zu erwarten war – beispielsweise bei Webhooks, von denen Sie wissen, dass sie von Stripe stammen – finden Sie weitere Hinweise in der Dokumentation zum Überprüfen von Webhook-Signaturen. Achten Sie insbesondere darauf, den richtigen Endopint-Geheimschlüssel zu verwenden. Dieser unterscheidet sich von Ihrem API-Schlüssel.