Weiter zum Inhalt
Konto erstellen
 oder
anmelden
Das Logo der Stripe-Dokumentation
/
Konto erstellen
Anmelden

Fehlerbehandlung

Erkennen und reagieren Sie auf Ablehnungen, ungültige Daten, Netzwerkprobleme und mehr.

Seite kopieren

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.

TechnikZweckWenn benötigt
Ausnahmen abfangenWiederherstellen, wenn ein API-Aufruf nicht fortgesetzt werden kannImmer
Webhooks überwachenAuf Benachrichtigungen von Stripe reagierenManchmal
Gespeicherte Informationen zu Fehlern erhaltenUntersuchen Sie frühere Probleme und unterstützen Sie andere TechnikenManchmal

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.

require 'stripe'

Stripe.api_key = 
'sk_test_BQokikJOvBiI2HlWgH4olfQ2'


def example_function(params)
  begin
    Stripe::PaymentIntent.create(params)
  rescue Stripe::CardError => e
    puts "A payment error occurred: #{e.error.message}"
  rescue Stripe::InvalidRequestError => e
    puts "An invalid request occurred."
  rescue Stripe::StripeError => e
    puts "Another problem occurred, maybe unrelated to Stripe."
  else
    puts "No error."
  end
end

Nachdem Sie den Umgang mit Ausnahmen eingerichtet haben, testen Sie diese mit verschiedenen Daten, einschließlich Testkarten, um unterschiedliche Zahlungsergebnisse zu simulieren.

example_function(
  # The required parameter currency is missing,
  amount: 2000,
  confirm: true,
  payment_method: 
'pm_card_visa'
,
)
console
An invalid request occurred.

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:

  1. Greifen Sie auf event.data.object zu, um das betreffende Objekt abzurufen.
  2. Verwenden Sie gespeicherte Informationen für das betroffene Objekt, um Kontext zu erhalten, einschließlich eines Fehlerobjekts.
  3. Verwenden Sie seinen Typ, um eine Antwort auszuwählen.
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 happened
  case 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 response
    case 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."
    end
  end

  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:

  1. Rufen Sie einen bestimmten Payment Intent ab.
  2. Überprüfen Sie, ob ein Zahlungsfehler aufgetreten ist, indem Sie feststellen, ob last_payment_error leer ist.
  3. Falls dies der Fall ist, protokollieren Sie den Fehler, einschließlich seines Typs und des betroffenen Objekts.
require 'stripe'
Stripe.api_key = 
'sk_test_BQokikJOvBiI2HlWgH4olfQ2'


payment_intent = Stripe::PaymentIntent.retrieve(
'{{PAYMENT_INTENT_ID}}'
)
e = payment_intent.last_payment_error
if !e.nil?
  puts "PaymentIntent #{payment_intent.id} experienced a #{e.type}."
end

Hier sind häufige Objekte, die Informationen zu Fehlern speichern.

ObjektAttributWerte
Payment Intentlast_payment_errorEin Fehlerobjekt
Setup Intentlast_setup_errorEin Fehlerobjekt
Rechnunglast_finalization_errorEin Fehlerobjekt
Einrichtungsversuchsetup_errorEin Fehlerobjekt
Auszahlungfailure_codeEin Fehlercode für eine Auszahlung
Rückerstattungfailure_reasonEin 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:

Fehler- und Antworttypen

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.

Name

Klasse

Beschreibung
Zahlungsfehler

Stripe::CardError

Während der Zahlung ist eine der folgenden Fehlersituationen aufgetreten:
Fehler „ungültige Anfrage“

Stripe::InvalidRequestError

Sie haben einen API-Aufruf mit den falschen Parametern, im falschen Status oder auf ungültige Weise ausgeführt.

Verbindungsfehler

Stripe::APIConnectionError

Zwischen Ihrem Server und Stripe ist ein Netzwerkproblem aufgetreten.
API-Fehler

Stripe::APIError

Auf der Seite von Stripe ist ein Fehler aufgetreten. (Dies kommt sehr selten vor).
Authentifizierungsfehler

Stripe::AuthenticationError

Stripe kann Sie mit den angegebenen Informationen nicht authentifizieren.
Idempotenzfehler

Stripe::IdempotencyError

Sie haben einen Idempotenz-Schlüssel für ein unerwartetes Ereignis verwendet, wie das Wiederholen einer Anfrage, jedoch mit Übergabe unterschiedlicher Parameter.
Berechtigungsfehler

Stripe::PermissionError

Der für diese Anfrage verwendete API-Schlüssel verfügt nicht über die erforderlichen Berechtigungen.
Ratenbegrenzungsfehler

Stripe::RateLimitError

Sie haben in zu kurzer Zeit zu viele API-Aufrufe getätigt.
Fehler beim Verifizieren der Signatur

Stripe::SignatureVerificationError

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:

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.)

require 'stripe'
Stripe.api_key = 
'sk_test_BQokikJOvBiI2HlWgH4olfQ2'


def example_function(params)
  begin
    Stripe::PaymentIntent.create(params)
  rescue Stripe::CardError => e
    charge = Stripe::Charge.retrieve(e.error.payment_intent.latest_charge)
    if charge.outcome.type == 'blocked'
      puts 'Payment blocked for suspected fraud.'
    elsif e.code == 'card_declined'
      puts 'Payment declined by the issuer.'
    elsif e.code == 'expired_card'
      puts 'Card expired.'
    else
      puts 'Other card error.'
    end
  end
end

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.)

require 'stripe'
Stripe.api_key = 
'sk_test_BQokikJOvBiI2HlWgH4olfQ2'


def example_function(params)
  begin
    Stripe::PaymentIntent.create(params)
  rescue Stripe::CardError => e
    if e.error.payment_intent.charges.data[0].outcome.type == 'blocked'
      puts 'Payment blocked for suspected fraud.'
    elsif e.code == 'card_declined'
      puts 'Payment declined by the issuer.'
    elsif e.code == 'expired_card'
      puts 'Card expired.'
    else
      puts 'Other card error.'
    end
  end
end

Mit Testkarten können Sie einige geläufige Arten von Zahlungsfehlern auslösen. In den folgenden Listen finden Sie Optionen:

Der folgende Testcode demonstriert einige Möglichkeiten.

example_function(
  currency: 'usd',
  amount: 2000,
  confirm: true,
  payment_method: 
'pm_card_radarBlock'
,
)
console
Payment blocked for suspected fraud.

Zahlung aufgrund Betrugsverdachts gesperrt

Typ

Stripe::CardError

Codes
charge = Stripe::Charge.retrieve(e.error.payment_intent.latest_charge)
charge.outcome.type == 'blocked'
Codes

e.error.payment_intent.charges.data[0].outcome.type == 'blocked'

ProblemRadar, 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:

  • Um eine bestimmte Zahlung auszunehmen, fügen Sie diese zu Ihrer Zulassungsliste hinzu. Radar for Fraud Teams
  • Passen Sie Ihre Risikoeinstellungen an, um Ihre Risikotoleranz zu ändern. Radar for Fraud Teams
  • Verwenden Sie nutzerspezifische Regeln, um die Kriterien für das Blockieren einer Zahlung zu ändern. Radar for Fraud Teams

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.

Zahlung vom Aussteller abgewiesen

Typ

Stripe::CardError

Codes

e.error.code == "card_declined"

ProblemDer Kartenaussteller hat die Zahlung abgelehnt.

Lösungen

This error can occur when your integration is working correctly. It reflects an action by the issuer, and that action might be legitimate. Use the decline code to determine what next steps are appropriate. See the documentation on decline codes for appropriate responses to each code.

Sie können auch:

Testen Sie mit Testkarten, die erfolgreiche und abgelehnte Zahlungen simulieren, wie Ihre Integration mit Ablehnungen umgeht.

Andere Zahlungsfehler

Typ

Stripe::CardError

ProblemEs ist ein weiterer Zahlungsfehler aufgetreten.
LösungenDieser 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

ProblemSie haben einen API-Aufruf mit den falschen Parametern, im falschen Status oder auf ungültige Weise ausgeführt.
LösungenIn 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.
  • Einzelheiten zu diesem Problem finden Sie in der Dokumentation zu Fehlercodes.
  • 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

ProblemZwischen Ihrem Server und Stripe ist ein Netzwerkproblem aufgetreten.

Lösungen

Treat the result of the API call as indeterminate. That is, don’t assume that it succeeded or that it failed.

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.

To help recover from connection errors, you can:

  • 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

ProblemAuf 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.

Authentifizierungsfehler

Typ

Stripe::AuthenticationError

ProblemStripe kann Sie mit den angegebenen Informationen nicht authentifizieren.
Lösungen

Idempotenz-Fehler

Typ

Stripe::IdempotencyError

ProblemSie 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

ProblemThe API key used for this request doesn’t have the necessary permissions.
Lösungen
  • Make sure you aren’t using a restricted API key for a service it doesn’t have access to.
  • Don’t perform actions in the Dashboard while logged in as a user role that lacks permission.

Ratenbegrenzungsfehler

Typ

Stripe::RateLimitError

ProblemSie 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

ProblemSie 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.

War diese Seite hilfreich?
JaNein
Benötigen Sie Hilfe? Kontaktieren Sie den Kundensupport.
Nehmen Sie an unserem Programm für frühzeitigen Zugriff teil.
Schauen Sie sich unser Änderungsprotokoll an.
Fragen? Sales-Team kontaktieren.
LLM? Lesen Sie llms.txt.
Unterstützt von Markdoc