Error handling

Catch and respond to declines, invalid data, network problems, and more.

Ruby

Python

PHP

Java

Node.js

Go

.NET

Stripe offers many kinds of errors. They can reflect external events, like declined payments and network interruptions, or code problems, like invalid API calls.

Parse error data

When Stripe returns an error to your API request, you receive details about the error that help you understand how to apply the handling suggestions in this guide. These details also help you provide important information to Stripe support, if needed.

To handle errors, use some or all of the techniques in the table below. No matter what technique you use, you can follow up with our recommended responses for each error type.

Catch exceptions

If an immediate problem prevents an API call from continuing, the Stripe Ruby library raises an exception. It’s a best practice to catch and handle exceptions.

To catch an exception, use Ruby’s rescue keyword. Catch Stripe::StripeError or its subclasses to handle Stripe-specific exceptions only. Each subclass represents a different kind of exception. When you catch an exception, you can use its class to choose a response.

Select a language

Ruby

Python

PHP

Java

Node.js

Go

.NET

No results

After setting up exception handling, test it on a variety of data, including test cards, to simulate different payment outcomes.

Error to trigger:

Select a language

Ruby

Python

PHP

Java

Node.js

Go

.NET

No results

example_function(
 # The required parameter currency is missing,
 amount: 2000,
 confirm: true,
 payment_method: 'pm_card_visa',
)

console

Select a language

Ruby

Python

PHP

Java

Node.js

Go

.NET

No results

An invalid request occurred.

Monitor webhooks

Stripe notifies you about many kinds of problems using webhooks. This includes problems that don’t follow immediately after an API call. For example:

• You lose a dispute.
• A recurring payment fails after months of success.
• Your front end confirms a payment, but goes offline before finding out the payment fails. (The back end still receives webhook notification, even though it wasn’t the one to make the API call.)

You don’t need to handle every webhook event type. In fact, some integrations don’t handle any.

In your webhook handler, start with the basic steps from the webhook builder: get an event object and use the event type to find out what happened. Then, if the event type indicates an error, follow these extra steps:

1. Access event.data.object to retrieve the affected object.
2. Use stored information on the affected object to gain context, including an error object.
3. Use its type to choose a response .

Select a language

Ruby

Python

PHP

Java

Node.js

Go

.NET

No results

require 'stripe'
require 'sinatra'

client = Stripe::StripeClient.new(ENV.fetch('STRIPE_API_KEY'))
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

To test how your integration responds to webhook events, you can trigger webhook events locally. After completing the setup steps at that link, trigger a failed payment to see the resulting error message.

Command Line

stripe trigger payment_intent.payment_failed

Output

A payment error occurred: Your card was declined.

Get stored information about failures

Many objects store information about failures. That means that if something already went wrong, you can retrieve the object and examine it to learn more. In many cases, stored information is in the form of an error object, and you can use its type to choose a response.

For instance:

1. Retrieve a specific payment intent.
2. Check if it experienced a payment error by determining if last_payment_error is empty.
3. If it did, log the error, including its type and the affected object.

Select a language

Ruby

Python

PHP

Java

Node.js

Go

.NET

No results

require 'stripe'
# Don't put any keys in code. See https://docs.stripe.com/keys-best-practices.
client = Stripe::StripeClient.new('sk_test_Ou1w6LVt3zmVipDVJsvMeQsc')

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

Here are common objects that store information about failures.

To test code that uses stored information about failures, you often need to simulate failed transactions. You can often do this using test cards or test bank numbers. For example:

• Simulate a declined payment , for creating failed Charges, PaymentIntents, SetupIntents, and so on.
• Simulate a failed payout .
• Simulate a failed refund .

Types of error and responses

In the Stripe Ruby library, error objects belong to stripe.error.StripeError and its subclasses. Use the documentation for each class for advice on responding.

Payment errors

Payment errors—sometimes called “card errors” for historical reasons—cover a wide range of common problems. They come in three categories:

• Payment blocked for suspected fraud
• Payment declined by the issuer
• Other payment errors

To distinguish these categories or get more information about how to respond, consult the error code, decline code, and charge outcome.

(To find the charge outcome from an error object, first get the Payment Intent that’s involved and the latest Charge it created. See the example below for a demonstration.)

Select a language

Ruby

Python

PHP

Java

Node.js

Go

.NET

No results

require 'stripe'

def example_function(params)
# Don't put any keys in code. See https://docs.stripe.com/keys-best-practices.
# Find your keys at https://dashboard.stripe.com/apikeys.
client = Stripe::StripeClient.new('sk_test_Ou1w6LVt3zmVipDVJsvMeQsc')
 begin
 client.v1.payment_intents.create(params)
 rescue Stripe::CardError => e
 charge = client.v1.charges.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

Users on API version 2022-08-01 or older:

(To find the charge outcome from an error object, first get the Payment Intent that’s involved and the latest Charge it created. See the example below for a demonstration.)

Select a language

Ruby

Python

PHP

Java

Node.js

Go

.NET

No results

require 'stripe'

def example_function(params)
# Don't put any keys in code. See https://docs.stripe.com/keys-best-practices.
# Find your keys at https://dashboard.stripe.com/apikeys.
client = Stripe::StripeClient.new('sk_test_Ou1w6LVt3zmVipDVJsvMeQsc')
 begin
 client.v1.payment_intents.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

You can trigger some common kinds of payment error with test cards. Consult these lists for options:

• Simulating payments blocked for fraud risk
• Simulating declined payments and other card errors

The test code below demonstrates a few possibilities.

Error to trigger:

Select a language

Ruby

Python

PHP

Java

Node.js

Go

.NET

No results

example_function(
 currency: 'usd',
 amount: 2000,
 confirm: true,
 payment_method: 'pm_card_radarBlock',
)

console

Select a language

Ruby

Python

PHP

Java

Node.js

Go

.NET

No results

Payment blocked for suspected fraud.

Payment blocked for suspected fraud

Payment declined by the issuer

Other payment errors

Invalid request errors

Connection errors

API errors

Authentication errors

Idempotency errors

Permission errors

Rate limit errors

Signature verification errors