Simple error handling strategies with Stripe Workbench

We’ve heard from the Stripe community that it is too hard to find data about errors which resulted from your Stripe API invocations. We have also heard that it would be helpful to provide more context and actionable advice once you do find the error. Now with the launch of the Stripe Workbench, developers have a birds-eye view of their integration which shows many potential issues in one place. This makes it easier to see the impact of each incident, see how often it’s happening, and receive actionable advice for resolving the issue.

What is a Stripe error

Stripe’s error handling system covers a wide array of potential issues which can arise during payment processing and API interactions. These include payment-specific errors like declined transactions and fraud prevention blocks, to technical hiccups such as network failures and authentication problems. Each of these errors is categorized into distinct groups called “error types.”

These types include StripeCardError for payment-related issues, StripeInvalidRequestError for incorrect API usage, StripeConnectionError for network problems, and several others for authentication, permissions, rate limits, and webhook verification.

Each error type is tailored to provide specific insights into what went wrong, allowing developers to implement targeted solutions and create robust, fault-tolerant integrations. You can utilize Workbench to maintain a good understanding of these diverse error types and how to properly handle them. This will help you to build smoother, higher conversion payment experiences.

Getting started with Workbench

To see Workbench:

1. Navigate to https://dashboard.stripe.com/ in your preferred browser and log into your Stripe account.

2. If you have multiple accounts configured, use the drop-down in the top-left to select the store API activity you wish to view. Workbench reports and content are scoped to the store level.

3. In the bottom-right corner of the browser, hover over the terminal icon to expand the menu, then select the caret symbol ^ to open Workbench.

4. Workbench opens in the lower portion of the window:

Workbench is not a browser extension and does not rely on CLIs or other tools in your development machine, so you can use it immediately without the need for installing additional software.

Finding errors with Stripe Workbench

Workbench features an Errors tab which provides a comprehensive overview of recent issues encountered in your Stripe account. This tab not only summarizes these errors but also offers guidance on resolving each specific type of API error. Additionally, it allows you to examine recent API request logs associated with each error, giving you valuable context for troubleshooting and improving your integration.

To view recent errors, choose the Errors tab. This view consists of three components, from left to right:

• A filterable list of recent errors within a given period (1 hour, 1 day, 7 days).
• A summary of the selected error.
• Logs associated with the error.

Errors which have occurred multiple times are grouped together and counted to help you identify those which are occurring most often.

In the following example, you see that the payment_intent_unexpected_state error has occurred 7 times during the past 7 days:

Choosing this error, opens the Summary and Logs view. This gives additional context about the error, and information about how to resolve it.

“You cannot confirm this PaymentIntent because it's missing a payment method. You can either update the PaymentIntent with a payment method and then confirm it again, or confirm it again directly with a payment method or ConfirmationToken.”

It also shows the request body sent with the API call that generated the error.

The Logs view shows the 7 API requests that produced the error message. Select any of these logs to dig deeper into that particular API request:

Choosing one of the logs displays in-depth information about the request such as the origin, the source, the API version and the request and response body of the API call:

Stripe integrations that are built using one of the Stripe SDKs each contain an error object with a type attribute. Use this to look up the types of error and responses from the Stripe docs page. Once you locate the error type, select it to view detailed actionable solutions. You can also use the doc_url attribute which links directly to the error-code handling page within the Stripe docs.

Strategies for handling errors

Stripe workbench helps you find, group, and solve errors within your Stripe integrations, but in addition to this there are some best practices you can use to handle errors as they occur in your integrations.

Catching inside your code

Try/catch blocks allow you to try an action and then if an exception occurs, catch the exception (error) and deal with it gracefully rather than crashing the entire application. This allows you to catch the specific error thrown by Stripe, interpret it, and provide a friendly, informative message to your user.

When you catch an exception, you can use its type attribute to choose a response. How you implement try/catch blocks will differ depending on the SDK runtime you are using. The following example shows a try/catch exception block using the Node.js SDK:

const stripe = require('stripe')('sk_test_123456');  
async function myFunction(args) {
  try {
    const paymentIntent = await stripe.paymentIntents.create(args);
    console.log('No error.');
  } catch (e) {
    switch (e.type) {
     case 'StripeInvalidRequestError':
        console.log('An invalid request occurred.');
        break;
case 'StripeCardError':
        console.log(`A payment error occurred: ${e.message}`);
        break;
      default:
        console.log('Some other problem occurred, maybe unrelated to Stripe.');
        break;
    } 
  }  
}

This script handles two different types of errors. If it's a StripeCardError, it logs that a payment error occurred along with the error message. If it's a StripeInvalidRequestError, it logs that an invalid request occurred. For any other type of error, it logs a generic message.

Reacting to events

Stripe can send events to webhook endpoints and cloud services, such as Amazon EventBridge to notify you of activity within your Stripe account. This can include errors. These events can occur both immediately after an API request or at a later time, such as when a payment is settled, a subscription renews, or when a payment fails. Webhooks ensure that your application stays in sync with the latest object updates allowing you to respond to events in near real-time and maintain accurate records of transactions and account activities.

You can use the Interactive webhook builder to set up and deploy a webhook that “listens” to Stripe events. When creating your webhook, you can use Workbench to specify which events to listen for. The following webhook is configured to listen only for payment_intent.payment_failed events.

When receiving events that relate to an error there are some sequential steps you should follow to “unpack” the event, pinpoint the error and take action to resolve:

1. Access event.data.object to retrieve the affected object: When Stripe sends a webhook event, the payload includes information about the event in the event.data.object property. This object contains details about the Stripe resource that triggered the event.

2. Obtain stored information about failures from event.data.object.last_payment_error. The webhook event object often includes an error object with additional context about what happened, including any errors that occurred.

3. Use the error type attribute (event.data.object.last_payment_error.type) to choose an appropriate response.

   The following code example demonstrates how to implement these three steps in Node.js:

 // Define a POST route to receive a payment intent error 
app.post('/webhook', express.json({type: 'application/json'}), (request, response) => {

  // 1. Get an event object
    const event = request.body;
    if (event.type == 'payment_intent.payment_failed') {

  //2.  Use stored information to get an error object
      const error = event.data.object.last_payment_error;

  //3. Use its type to choose a response
      switch (error.type) {
        case 'card_error':
          console.log(`A payment error occurred: ${error.message}`);
          break;
        default:
          console.log('Another problem occurred, maybe unrelated to Stripe.');
          break;
      }
    } 
    response.send();
  });

Webhooks deliveries can also fail for various reasons. You can view the delivery success of each webhook in the Workbench Webhooks tab. Here you can also filter by delivery status.

Retrieve historical errors

The previous example receives a webhook event when a paymentIntent failure occurs and accesses the last_payment_error attribute to retrieve additional information about the error. Many other Stripe objects store previous error information in this way. Use this same technique on these objects to access the previous error type and refer to the documentation for each type for advice about how to respond:

These are common objects that store information about failures, and the attribute you should use to access that information.

OBJECT	ATTRIBUTE	VALUES
Payment Intent	last_payment_error	An error object
Setup Intent	last_setup_error	An error object
Invoice	last_finalization_error	An error object
Setup Attempt	setup_error	An error object
Payout	failure_code	A payout failure code
Refund	failure_reason	A refund failure code

For example, use the following Node.js code to access previous failure information for a SetupIntent:

const setup_intent = await stripe.setupIntents.retrieve('{{SETUP_INTENT_ID}}')  
const e = setup_intent.last_setup_error

if (e !== null) {  
  console.log(`SetupIntent  ${setup_intent.id} experienced a ${e.type} error.`)  
}

Conclusion

Workbench addresses common challenges you face when handling errors in building Stripe integrations. It centralizes error reporting, providing you with a comprehensive view of recent issues, their frequency, and contextual information for efficient troubleshooting.

Using Workbench, combined with established error handling strategies enables more robust integrations. Some approaches discussed include implementing try-catch exceptions to gracefully manage errors, using webhooks to react to events, and accessing stored error information on Stripe objects.

By employing these methods and using Workbench's features such as grouped error views, detailed logs, and actionable advice, you can more effectively identify, understand, and resolve integration issues. This approach to error management supports the creation of more reliable payment systems, ultimately improving the overall user experience in online transactions.