Why?

Earlier this year, we noticed that the Node SDK's error handling algorithm was less precise than the other SDKs. Notably, it didn't let users handle OAuth-related errors as precisely as they should be able to.

There are some breaking changes as part of this work. Mainly, there are more error classes than before, so existing error-handling code may need to change. See the migration guide below for more info.

What?

• add new error class (StripeOAuthError) and associated child classes (StripeInvalidClientError, etc)
• ⚠️ remove Stripe.errors.StripeUnknownError in favor of StripeAPIError
• ⚠️ amend rawType union to include all the new types
• update tests
• remove some redundant checks (e.g. 429 status is checked in two places)

See Also

• DEVSDK-2914

Changleog

• There are now more error classes to more accurately model errors returned from the API. See the migration guide in the original PR for more info.

Migration Guide

The SDK's error classes have moved around a bit, so your error handling code may need adjustments. This is especially relevant if you're checking if errors are instanceof specific Stripe.errors.ABC classes.

StripeUnknownError removed

StripeUnknownError was always redundant with StripeAPIError, so we've consolidated around the latter. It continues to represent errors from the Stripe API that don't have more specific types present. You're unlikely to encounter this error type (especially if your API version matches the SDK you're using). If you were using StripeUnknownError to handle OAuth issues, use the new classes (see below).

The best way to handle unexpected errors is still to catch StripeError directly, since all of our Exception classes inherit from that.

New OAuth Errors

The Exception class hierarchy has changed slightly. There's a new StripeOAuthError to collect all OAuth-related errors

StripeError
└── StripeOAuthError (NEW)
    ├── StripeInvalidGrantError (MOVED; previously extended StripeError directly)
    ├── StripeInvalidClientError (NEW)
    ├── StripeOAuthInvalidRequestError (NEW)
    ├── StripeInvalidScopeError (NEW)
    ├── StripeUnsupportedGrantTypeError (NEW)
    └── StripeUnsupportedResponseTypeError (NEW)

This should be compatible with existing code, but it's worth noting that StripeInvalidGrantError is no longer a direct child of StripeError. It's now a grandchild (via StripeOAuthError).

New values in RawErrorType

The Stripe.RawErrorType string literal type has new values to better reflect the errors you may have to handle. (No changes have happened on the API side; the library is just more accurate.)

If you have code that performs type narrowing on Stripe.RawErrorType, you'll likely need to account for the new types.