`instanceof Stripe.ErrorType.StripeError` passes type check but throws at runtime

[egorFiNE]

Describe the bug

Unsure how to catch Stripe errors in catch(err: any) {... }.

To Reproduce

Before (v21):

} catch (e: any) {
  if (e instanceof Stripe.ErrorType && e.statusCode === 404) {
    // ... 
  }
}

Now this code triggers a ts error because obviously. I'm using TS 6.0.

Expected behavior

Not sure what would the correct way of separating Stripe Error instances from others in the update type system.

Code snippets

OS

doesn't matter

Node version

doesn't matter

Library version

v22.0.0

API version

2026-03-25.dahlia

Additional context

With a slim hope that management sees this feedback:

Stop it, just stop. I feel like every new Stripe SDK release lately brings unwelcome and breaking changes and more useless work that brings zero value to anyone involved except Stripe's developers.

Stripe started as a product for developers to eliminate frustration and reduce friction.

Now Stripe is itself a source of frustration since each new SDK version (since about v17) adds friction.

[prathmesh-stripe]

Stripe.error.ErrorType is now the class constructor itself, can you try the following:

try {
} catch (e: any) {
  if (e instanceof Stripe.error.ErrorType && e.statusCode === 404) {
    // ... 
  }
}

[egorFiNE]

@prathmesh-stripe

Property 'ErrorType' does not exist on type 'typeof import("...stripe/esm/Error", { with: { "resolution-mode": "import" } })

[xavdid]

Hey @egorFiNE, sorry for the hassle here. I've been playing around with error handling and casting and wasn't able to reproduce your issue. This is what i've got (using TS 6.0 and v20.4.1 of the node SDK):

import { Stripe } from "stripe";

const stripeClient = new Stripe("sk_test_123");

try {
  await stripeClient.customers.list();
} catch (error) {
  // auth error, since it's not a real API key
  console.log((error as Stripe.errors.StripeError).statusCode); // 401
  console.log(error instanceof Stripe.errors.StripeError); // true
}

When migrating to v22 (with all the type changes), I needed to swap the way I referred to the error type (not runtime class):

import { Stripe } from "stripe";

const stripeClient = new Stripe("sk_test_123");

try {
  await stripeClient.customers.list();
} catch (error) {
  // auth error, since it's not a real API key
- console.log((error as Stripe.errors.StripeError).statusCode); // 401
+ console.log((error as Stripe.ErrorType.StripeError).statusCode); // 401
  console.log(error instanceof Stripe.errors.StripeError); // true
}

The runtime code didn't need to change.

That said, I'm a little confused by your example because Stripe.ErrorType didn't exist in v20 of the SDK. Do you mind posting an example of your original working setup, including how you import and instantiate Stripe?

[egorFiNE]

@xavdid here's me having to apologize because I myself fell into a trap of blindly accepting LLM suggestions. My original bugreport with Stripe.ErrorType is a typo and moot. I do apologize!

Suggestion to use Stripe.error.ErrorType was incorrect as well.

---

However right now both of these variants:

if (error instanceof Stripe.errors.StripeError)  {
  console.log("instanceof Stripe.errors.StripeError");
}

if (error instanceof Stripe.ErrorType.StripeError) {
  console.log("instanceof Stripe.ErrorType.StripeError");
}

...they both pass eslint with airbnb rules (the extended one), oxlint and tsc -b.

Great! Except one of them fails at runtime:

16 |   if (error instanceof Stripe.ErrorType.StripeError) {
                                   ^
TypeError: undefined is not an object (evaluating 'Stripe.ErrorType.StripeError')
      at /Users/egor/workspace/dehancer/dhs/src/test1.ts:16:31

So do I get it right that runtime types and typescript types are different now?

stripe sdk is 22.0.0. Typescript 6.0.2. Using both bun 1.3.11 and node 25.9.0.

[xavdid]

My original bugreport with Stripe.ErrorType is a typo and moot. I do apologize!

No problem at all! There are a lot of moving pieces with this release and we appreciate your patience.

---

This is a bug we've got filed internally already, the second example should give a typescript error:

if (error instanceof Stripe.ErrorType.StripeError) { // should give ⬇️
  // ^ The right-hand side of an 'instanceof' expression must be either of 
  // type 'any', a class, function, or other type assignable to the 'Function' 
  // interface type, or an object type with a 'Symbol.hasInstance' method
  console.log("instanceof Stripe.ErrorType.StripeError"); 
}

Stripe.ErrorType.StripeError should only describes the type, not the runtime class. We're having to do some gymnastics because of the way a many of our classes are also TS namespaces and we wanted to keep as much backwards compatibility as possible while still paying down this tech debt. There are a lot of edge cases. 😅

So definitely stick with error instanceof Stripe.errors.StripeError for runtime checks and we'll get the surprise runtime error fixed up. I'll rename this GH issue accordingly

[egorFiNE]

@xavdid thanks, appreciate it.

There are a lot of edge cases.

It sure seems like the Stripe TS SDK is drowning in it.

This is why I have finally decided to switch to raw REST API (with a small helper), because it doesn't feel like the SDK is adding value at this point.