Fehlerbehandlung
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.
Technik | Zweck | Wenn benötigt |
---|---|---|
Fehlerwerte verwenden | Wiederherstellen, wenn ein API-Aufruf nicht fortgesetzt werden kann | Immer |
Webhooks überwachen | Auf Benachrichtigungen von Stripe reagieren | Manchmal |
Gespeicherte Informationen zu Fehlern erhalten | Untersuchen Sie frühere Probleme und unterstützen Sie andere Techniken | Manchmal |
Fehlerwerte verwenden
API-Aufrufe in der Go-Bibliothek von Stripe geben sowohl einen Ergebniswert als auch einen Fehlerwert zurück. Verwenden Sie die mehrfache Zuweisung, um beide zu erfassen. Ist der Fehlerwert nicht nil
, bedeutet dies, dass ein unmittelbares Problem die Fortsetzung des API-Aufrufs verhindert hat.
Wenn sich der Fehlerwert auf Stripe bezieht, können Sie ihn in ein stripe.
-Objekt umwandeln, das Felder enthält, die das Problem beschreiben. Verwenden Sie das Feld „Typ“, um eine Antwort auszuwählen. In einigen Fällen können Sie die Eigenschaft Err
auf einen spezifischeren Fehlertyp mit zusätzlichen Informationen umstellen.
Nachdem Sie den Umgang mit Ausnahmen eingerichtet haben, testen Sie diese mit verschiedenen Daten, einschließlich Testkarten, um unterschiedliche Zahlungsergebnisse zu simulieren.
Webhooks überwachen
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:
- Holen Sie sich das betroffene Objekt, indem Sie Daten aus
event.
zurückwandeln.Data. Raw - Verwenden Sie gespeicherte Informationen für das betroffene Objekt, um Kontext zu erhalten, einschließlich eines Fehlerobjekts.
- Verwenden Sie seinen Typ, um eine Antwort auszuwählen.
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.
stripe trigger payment_intent.payment_failed
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.
Hier sind häufige Objekte, die Informationen zu Fehlern speichern.
Objekt | Attribut | Werte |
---|---|---|
Payment Intent | last_ | Ein Fehlerobjekt |
Setup Intent | last_ | Ein Fehlerobjekt |
Rechnung | last_ | Ein Fehlerobjekt |
Einrichtungsversuch | setup_ | Ein Fehlerobjekt |
Auszahlung | failure_ | Ein Fehlercode für eine Auszahlung |
Rückerstattung | failure_ | Ein Fehlercode für eine Rückerstattung |
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:
- Simulieren Sie eine abgelehnte Zahlung zum Erstellen fehlgeschlagener Abbuchungen, PaymentIntents, SetupIntents usw.
- Eine fehlgeschlagene Auszahlung simulieren.
- Eine fehlgeschlagene Rückerstattung simulieren.
Fehler- und Antworttypen
In der Stripe Go-Bibliothek hat jedes Fehlerobjekt ein Type
-Attribut. Hinweise zum richtigen Vorgehen finden Sie in der Dokumentation zu den einzelnen Typen.
Name | Typ | Beschreibung |
---|---|---|
Zahlungsfehler | Während der Zahlung ist eine der folgenden Fehlersituationen aufgetreten: | |
Fehler „ungültige Anfrage“ | Sie haben einen API-Aufruf auf eine Weise ausgeführt, die derzeit nicht gültig ist. Dies kann Folgendes beinhalten: | |
API-Fehler | Auf der Seite von Stripe ist ein Fehler aufgetreten. (Dies kommt sehr selten vor). | |
Idempotenzfehler | Sie haben einen Idempotenz-Schlüssel für ein unerwartetes Ereignis verwendet, wie das Wiederholen einer Anfrage, jedoch mit Übergabe unterschiedlicher Parameter. |
Kartenfehler
Zahlungsfehler – aus historischen Gründen auch manchmal als „Kartenfehler“ bezeichnet – decken ein breites Spektrum geläufiger Probleme ab. Sie sind auf drei Kategorien verteilt:
Um diese Kategorien zu unterscheiden oder weitere Informationen zur Reaktion zu erhalten, sehen Sie unter Fehlercode, Ablehnungscode und Zahlungsergebnis nach.
(Um das Zahlungsergebnis von einem Fehlerobjekt zu finden, rufen Sie zuerst den betroffenen Payment Intent und die neueste von ihm erstellte Zahlung auf. Im nachfolgenden Beispiel wird dies veranschaulicht.)
Nutzer/innen mit API-Version 2022-08-01 oder älter:
(Um das Zahlungsergebnis von einem Fehlerobjekt zu finden, rufen Sie zuerst den betroffenen Payment Intent und die neueste von ihm erstellte Zahlung auf. Im nachfolgenden Beispiel wird dies veranschaulicht.)
Mit Testkarten können Sie einige geläufige Arten von Zahlungsfehlern auslösen. In den folgenden Listen finden Sie Optionen:
- Aufgrund von Betrugsrisiko gesperrte Zahlungen simulieren
- Abgelehnte Zahlungen und andere Kartenfehler simulieren
Der folgende Testcode demonstriert einige Möglichkeiten.
Aufgrund Betrugsverdachts gesperrt
Typ |
|
Codes |
|
Codes |
|
Problem | 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:
Kund/innen von Radar for Fraud Teams stehen folgende zusätzliche Optionen zur Verfügung:
Sie können die Einstellungen Ihrer Integration mit Testkarten, die Betrug simulieren testen. Wenn Sie nutzerdefinierte Radar-Regeln haben, folgen Sie den Test-Hinweisen in der Dokumentation von Radar. |
Vom Aussteller abgewiesen
Typ |
|
Codes |
|
Problem | Der Kartenaussteller hat die Zahlung abgelehnt. |
Lösungen | 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. Sie können auch:
Testen Sie mit Testkarten, die erfolgreiche und abgelehnte Zahlungen simulieren, wie Ihre Integration mit Ablehnungen umgeht. |
Andere Zahlungsfehler
Typ |
|
Problem | Es ist ein weiterer Zahlungsfehler aufgetreten. |
Lösungen | 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
Fehler aufgrund einer ungültigen Anforderung decken eine Reihe von Situationen ab. Am häufigsten tritt dies auf, wenn die API-Anfrage ungültige Parameter enthält oder im aktuellen Status Ihrer Integration nicht zulässig ist. Verwenden Sie den Fehlercode (stripeErr.
) und schlagen Sie in der Fehlercode-Dokumentation nach, um eine Lösung zu finden. Einige Fehlercodes erfordern eine spezielle Reaktion:
rate_
andlimit lock_
spiegeln Ratenbegrenzungsfehler widertimeout secret_
spiegelt einen Authentifizierungsfehler widerkey_ required - Andere Fehlercodes spiegeln ungültige Parameter oder Status wider
Ratenbegrenzungsfehler
Typ |
|
Codes | stripeErr. |
Problem | Sie haben in zu kurzer Zeit zu viele API-Aufrufe getätigt. |
Lösungen |
|
Authentifizierungsfehler
Typ |
|
Codes | stripeErr. |
Problem | Stripe kann Sie mit den angegebenen Informationen nicht authentifizieren. |
Lösungen |
|
Ungültige Parameter oder Status
Typ |
|
Codes | stripeErr. |
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.
|
API-Fehler
Typ |
|
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. Um Ihre Integration so solide wie möglich für ungewöhnliche Situationen zu gestalten, informieren Sie sich unter dieser erweiterten Diskussion zu Serverfehlern. |
Idempotenz-Fehler
Typ |
|
Problem | Sie haben einen Idempotenz-Schlüssel für ein unerwartetes Ereignis verwendet, wie das Wiederholen einer Anfrage, jedoch mit Übergabe unterschiedlicher Parameter. |
Lösungen |
|