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 Node.js-Bibliothek von Stripe eine Ausnahme aus. Dies ist ein bewährtes Verfahren, um Ausnahmen abzufangen und zu handhaben. Um das Auslösen von Ausnahmen zu aktivieren und die Ausnahme abzufangen, gehen Sie wie folgt vor: Zum Auslösen und Abfangen der Ausnahme gehören mehrere Schritte:
Wenn Sie den API-Aufruf in einer Funktion ausführen, stellen Sie der Funktionsdefinition das Schlüsselwort async voran.
Stellen Sie dem API-Aufruf selbst das Schlüsselwort await voran.
Schließen Sie den API-Aufruf in einen try/catch-Block ein.
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.
);const express =require('express');const app =express();
app.post('/webhook', express.json({type:'application/json'}),(request, response)=>{// Get an event objectconst event = request.body;// Use its type to find out what happenedif(event.type=='payment_intent.payment_failed'){// Get the object affectedconst paymentIntent = event.data.object;// Use stored information to get an error objectconst error = paymentIntent.error;// Use its type to choose a responseswitch(error.type){case'StripeCardError':
console.log(`A payment error occurred: ${error.message}`);break;case'StripeInvalidRequestError':
console.log('An invalid request occurred.');if(error.param){
console.log(`The parameter ${error.param} is invalid or missing.`);}break;default:
console.log('Another problem occurred, maybe unrelated to Stripe.');break;}}
response.send();});
app.listen(4242,()=> console.log('Running on port 4242'));
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 Node.js-Bibliothek hat jedes Fehlerobjekt ein type-Attribut. Hinweise zum richtigen Vorgehen finden Sie in der Dokumentation zu den einzelnen Typen.
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, wenn Ihre Integration korrekt funktioniert. Er gibt eine Aktion des Ausstellers wider, 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, wenn 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
StripeInvalidRequestError
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 e.doc_url erhalten Sie schnellen Zugriff auf Dokumentation zum Fehlercode.
Wenn der Fehler einen bestimmten Parameter beinhaltet, verwenden Sie e.param, um diesen zu bestimmen.
Verbindungsfehler
Typ
StripeAPIConnectionError
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
StripeAPIError
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
StripePermissionError
Problem
Der für diese Anfrage verwendete API-Schlüssel verfügt nicht über die erforderlichen Berechtigungen.
Are you performing an action in the Dashboard while logged in as a user role that lacks permission?
Ratenbegrenzungsfehler
Typ
StripeRateLimitError
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
StripeSignatureVerificationError
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.
Welcome to the Stripe Shell!
Stripe Shell is a browser-based shell with the Stripe CLI pre-installed. Log in to your
Stripe account and press Control + Backtick (`) on your keyboard to start managing your Stripe
resources in test mode.
- View supported Stripe commands:
- Find webhook events:
- Listen for webhook events:
- Call Stripe APIs: stripe [api resource] [operation] (e.g., )
Stripe Shell wurde für die Verwendung am Desktop konzipiert.