Weiter zum Inhalt
Konto erstellen
oder
anmelden
Das Logo der Stripe-Dokumentation
/
KI fragen
Konto erstellen
Anmelden
Jetzt starten
Zahlungen
Umsatz
Plattformen und Marktplätze
Geldmanagement
Entwickler-Tools
Übersicht
Versionierung
Änderungsprotokoll
Aktualisieren Sie Ihre API-Version
Ihre SDK-Version aktualisieren
Entwickler-Tools
SDKs
API
    API v2
    API-Schlüssel
    Stripe-Context-Header
    Tägliches Änderungsprotokoll
    Ratenbegrenzungen
    Automatische Tests
    Metadaten
    Erweiterung der Antworten
    Paginierung
    Domains und IP-Adressen
    Suchen
    Lokalisierung
    Fehlerbehandlung
      Erweiterte Fehlerbehebung
    Fehlercodes
Tests
Workbench
Ereignisziele
Arbeitsabläufe
Stripe-CLI
Stripe Shell
Entwickler-Dashboard
Agent-Toolkit
Mit LLMs entwickelnStripe für Visual Studio CodeStripe-StatuswarnungenHochgeladene Dateien
Sicherheit und Datenschutz
Sicherheit
Datenschutz
Extend Stripe
Stripe-Apps
Stripe Connectors
Partner
Partner-Ecosystem
Partner-Zertifizierung
StartseiteEntwickler-ToolsAPI

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
Fehlerwerte verwendenWiederherstellen, 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

Fehlerwerte verwenden

Fehler und HTTP

Mit dieser Bibliothek müssen Sie nicht nach „non-200 HTTP“-Antworten suchen. Die Bibliothek übersetzt sie als Fehlerwerte.

Für den seltenen Fall, dass Sie HTTP-Details benötigen, lesen Sie Umgang mit einfachen Ausnahmen und das Fehler-Objekt.

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

Go
package main import ( "github.com/stripe/stripe-go/v72" "github.com/stripe/stripe-go/v72/paymentintent" "log" ) func example_function(params *stripe.PaymentIntentParams) { stripe.Key =
"sk_test_BQokikJOvBiI2HlWgH4olfQ2"
_, err := paymentintent.New(params) if err == nil { log.Println("No error.") } else { if stripeErr, ok := err.(*stripe.Error); ok { switch stripeErr.Type { case stripe.ErrorTypeCard: log.Println("A payment error occurred:", stripeErr.Msg) case stripe.ErrorTypeInvalidRequest: log.Println("An invalid request occurred.") default: log.Println("Another Stripe error occurred.") } } else { log.Println("An error occurred that was unrelated to Stripe.") } } }

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

Go
params := &stripe.PaymentIntentParams{ Amount: stripe.Int64(2000), // The required parameter currency is missing Confirm: stripe.Bool(true), PaymentMethod: stripe.String(
"pm_card_visa"
), } example_function(params)
console
Go
1749848809 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. Holen Sie sich das betroffene Objekt, indem Sie Daten aus event.Data.Raw zurückwandeln.
  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.
Go
package main import ( "encoding/json" "io/ioutil" "log" "net/http" "github.com/stripe/stripe-go/v72" "github.com/stripe/stripe-go/v72/webhook" ) func main() { http.HandleFunc("/webhook", handleWebhook) addr := "localhost:4242" log.Printf("Listening on %s", addr) log.Fatal(http.ListenAndServe(addr, nil)) } func handleWebhook(w http.ResponseWriter, req *http.Request) { const MaxBodyBytes = int64(65536) req.Body = http.MaxBytesReader(w, req.Body, MaxBodyBytes) payload, err := ioutil.ReadAll(req.Body) if err != nil { log.Printf("Error reading request body: %v\n", err) w.WriteHeader(http.StatusServiceUnavailable) return } // Replace this endpoint secret with your endpoint's unique secret // If you are testing with the CLI, find the secret by running 'stripe listen' // If you are using an endpoint defined with the API or dashboard, look in your webhook settings // at https://dashboard.stripe.com/webhooks endpointSecret := "whsec_..." signatureHeader := req.Header.Get("Stripe-Signature") // Get an event object event, err := webhook.ConstructEvent(payload, signatureHeader, endpointSecret) if err != nil { log.Printf("⚠️ Webhook signature verification failed. %v\n", err) w.WriteHeader(http.StatusBadRequest) // Return a 400 error on a bad signature return } // Use its type to find out what happened switch event.Type { case "payment_intent.payment_failed": // Get the object affected by unmarshalling event data into // the appropriate struct for the event type var paymentIntent stripe.PaymentIntent err := json.Unmarshal(event.Data.Raw, &paymentIntent) if err != nil { log.Printf("Error parsing webhook JSON: %v\n", err) w.WriteHeader(http.StatusBadRequest) return } // Use stored data to get an error object e := paymentIntent.LastPaymentError // Use its type to choose a response switch e.Type { case "card_error": log.Println("A payment error occurred: ", e.Msg) case "invalid_request": log.Println("An invalid request occurred.") default: log.Println("Another problem occurred, maybe unrelated to Stripe.") } default: log.Println("Unhandled event type: ", event.Type) } w.WriteHeader(http.StatusOK) }

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.
Go
stripe.Key =
"sk_test_BQokikJOvBiI2HlWgH4olfQ2"
pi, _ := paymentintent.Get(
"{{PAYMENT_INTENT_ID}}"
, nil, ) paymentErr := pi.LastPaymentError if paymentErr != nil { log.Printf("PaymentIntent %s experienced a %s error.", pi.ID, paymentErr.Type) }

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:

  • 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

stripe.ErrorTypeCard

Während der Zahlung ist eine der folgenden Fehlersituationen aufgetreten:
  • Zahlung wegen Betrugsverdachts blockiert
  • Zahlung von Aussteller abgewiesen.
  • Andere Zahlungsfehler.
Fehler „ungültige Anfrage“

stripe.ErrorTypeInvalidRequest

Sie haben einen API-Aufruf auf eine Weise ausgeführt, die derzeit nicht gültig ist. Dies kann Folgendes beinhalten:

  • Fehler bei der Ratenbegrenzung
  • Authentifizierungsfehler
  • Ungültige Parameter oder ungültiger Status
API-Fehler

stripe.ErrorTypeAPI

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

stripe.ErrorTypeIdempotency

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

Kartenfehler

Fehler, die nicht mit Kartenzahlungen verbunden sind

Alle Angaben in diesem Abschnitt gelten auch für Zahlungen ohne Karte. Aus historischen Gründen haben Zahlungsfehler den Typ stripe. ErrorTypeCard. Tatsächlich können sie aber bei jeder Zahlung ein Problem darstellen, unabhängig von der Zahlungsmethode.

Zahlungsfehler – aus historischen Gründen auch manchmal als „Kartenfehler“ bezeichnet – decken ein breites Spektrum geläufiger Probleme ab. Sie sind auf drei Kategorien verteilt:

  • Zahlung wegen Betrugsverdachts blockiert
  • Zahlung von Aussteller abgewiesen
  • Andere Zahlungsfehler

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

Go
func example_function(params *stripe.PaymentIntentParams) { stripe.Key =
"sk_test_BQokikJOvBiI2HlWgH4olfQ2"
_, err := paymentintent.New(params) if err == nil { log.Println("No error.") } else { if stripeErr, ok := err.(*stripe.Error); ok { if stripeErr.Type == stripe.ErrorTypeCard { charge = Charge.retrieve(stripeErr.PaymentIntent.LatestCharge) if charge.Outcome.Type == "blocked" { log.Println("Payment blocked for suspected fraud.") } else if stripeErr.Code == stripe.ErrorCodeCardDeclined { log.Println("Declined by the issuer.") } else if stripeErr.Code == stripe.ErrorCodeExpiredCard { log.Println("Card expired.") } else { log.Println("Other card error.") } } } } }

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

Go
func example_function(params *stripe.PaymentIntentParams) { stripe.Key =
"sk_test_BQokikJOvBiI2HlWgH4olfQ2"
_, err := paymentintent.New(params) if err == nil { log.Println("No error.") } else { if stripeErr, ok := err.(*stripe.Error); ok { if stripeErr.Type == stripe.ErrorTypeCard { if stripeErr.PaymentIntent.Charges.Data[0].Outcome.Type == "blocked" { log.Println("Payment blocked for suspected fraud.") } else if stripeErr.Code == stripe.ErrorCodeCardDeclined { log.Println("Declined by the issuer.") } else if stripeErr.Code == stripe.ErrorCodeExpiredCard { log.Println("Card expired.") } else { log.Println("Other card error.") } } } } }

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.

Go
params := &stripe.PaymentIntentParams{ Amount: stripe.Int64(2000), Currency: stripe.String(string(stripe.CurrencyUSD)), Confirm: stripe.Bool(true), PaymentMethod: stripe.String(
"pm_card_radarBlock"
), } example_function(params)
console
Go
1749848809 Payment blocked for suspected fraud.

Aufgrund Betrugsverdachts gesperrt

Typ

stripe.ErrorTypeCard

Codes
charge = Charge.retrieve(stripeErr.PaymentIntent.LatestCharge) charge.Outcome.Type == "blocked"
Codes

stripeErr.PaymentIntent.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:

  • Ihre Radar-Integration optimieren, um detailliertere Informationen zu erfassen.
  • Verwenden Sie Payment Links, Checkout oder Stripe Elements für vorgefertigte, optimierte Formularelemente.

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.

Vom Aussteller abgewiesen

Typ

stripe.ErrorTypeCard

Codes

cardErr.Error.Code == stripe.ErrorCodeCardDeclined

ProblemDer Kartenaussteller hat die Zahlung abgelehnt.

Lösungen

Dieser Fehler kann auftreten, obwohl Ihre Integration korrekt funktioniert. Er weist auf eine Aktion des Ausstellers 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:

  • Befolgen Sie die Empfehlungen, um die Ablehnungen durch Aussteller zu reduzieren.
  • Verwenden Sie Payment Links, Checkout oder Stripe Elements für vorgefertigte Formularelemente, die diese Empfehlungen implementiert haben.

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

Andere Zahlungsfehler

Typ

stripe.ErrorTypeCard

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

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.Code) und schlagen Sie in der Fehlercode-Dokumentation nach, um eine Lösung zu finden. Einige Fehlercodes erfordern eine spezielle Reaktion:

  • rate_limit and lock_timeout spiegeln Ratenbegrenzungsfehler wider
  • secret_key_required spiegelt einen Authentifizierungsfehler wider
  • Andere Fehlercodes spiegeln ungültige Parameter oder Status wider

Ratenbegrenzungsfehler

Typ

stripe.ErrorTypeInvalidRequest

CodesstripeErr.Code == stripe.ErrorCodeRateLimit or stripeErr.Code == stripe.ErrorCodeLockTimeout
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.

Authentifizierungsfehler

Typ

stripe.ErrorTypeInvalidRequest

CodesstripeErr.Code == stripe.ErrorCodeSecretKeyRequired
ProblemStripe kann Sie mit den angegebenen Informationen nicht authentifizieren.
Lösungen
  • Verwenden Sie den korrekten API-Schlüssel.
  • Stellen Sie sicher, dass Sie keinen Schlüssel verwenden, den Sie „rotiert“ oder widerrufen haben.

Ungültige Parameter oder Status

Typ

stripe.ErrorTypeInvalidRequest

CodesstripeErr.Code != stripe.ErrorCodeRateLimit and stripeErr.Code != stripe.ErrorCodeLockTimeout and stripeErr.Code != stripe.ErrorCodeSecretKeyRequired
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 stripeErr.DocURL erhalten Sie schnellen Zugriff auf Dokumentation zum Fehlercode.
  • Wenn der Fehler einen bestimmten Parameter beinhaltet, verwenden Sie stripeErr.Param, um diesen zu bestimmen.

API-Fehler

Typ

stripe.ErrorTypeAPI

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.

Idempotenz-Fehler

Typ

stripe.ErrorTypeIdempotency

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