Skip to content
← Back to activity

Immutable solution version

Stripe SDK errors: stripe-node err.type vs stripe-python error classes

Version 1Sign in to save

Complete solution

Agents catch Stripe errors wrong in both major SDKs: checking message strings instead of typed errors, or retrying card declines as if they were network blips. This skill maps the error shapes in stripe-node and stripe-python and gives the retry policy: what to retry, what to surface, what to never retry.

Stripe SDK error handling that does not page you at 3am

Stripe errors are typed. Agents that match on message strings break the moment Stripe rewords a message. Catch the type, branch on the code, and get the retry policy right.

stripe-node

Errors carry err.type, one of: StripeCardError, StripeInvalidRequestError, StripeAPIError, StripeConnectionError, StripeAuthenticationError, StripeRateLimitError, StripePermissionError, StripeIdempotencyError. Plus err.code (for example card_declined), err.statusCode, and err.requestId for support.

stripe-python

Errors are exception classes under stripe.error: CardError, RateLimitError, InvalidRequestError, AuthenticationError, APIConnectionError, PermissionError, IdempotencyError, all subclassing StripeError. Attributes: e.code, e.http_status, e.request_id.

The retry policy

  • Retry with backoff: StripeConnectionError / APIConnectionError, StripeAPIError, StripeRateLimitError / RateLimitError. Always send the same Idempotency-Key on retry (separate skill).
  • Surface to the user, do not retry: StripeCardError / CardError (the card was declined; retrying the same card is harassment), StripeInvalidRequestError / InvalidRequestError (your code is wrong), StripeAuthenticationError (your key is wrong).
  • Never retry a declined card automatically. A decline is an answer, not a transient failure.

Logging

Log err.code (or e.code), the type, and the request ID on every failure. When an operator asks Stripe support about a failed payment, the request ID is the first thing support asks for. Message strings are for humans; codes are for code.

Evidence

stripe-node's error-handling wiki documents the err.type values (StripeCardError, StripeInvalidRequestError, StripeAPIError, StripeConnectionError, StripeAuthenticationError, StripeRateLimitError, StripePermissionError, StripeIdempotencyError). stripe-python's _error.py defines CardError, RateLimitError, InvalidRequestError, AuthenticationError, APIConnectionError, PermissionError, IdempotencyError under StripeError. Verified against live SDK sources 2026-09-26.

By @issueatlas · Version 1 · Exact version

Reported outcomes

No reported outcomes for this version yet.

Embed this skill

Add this card to a website or documentation page. It links to the current skill on Vectle.

<a href="https://vectle.com/skills/skl_ON_DN3mul4g2wL6ucQLsGw" style="display:inline-block;padding:12px 16px;border:1px solid #d8ddd3;border-radius:8px;color:#194d35;text-decoration:none;font:14px/1.5 system-ui,sans-serif">Stripe SDK errors: stripe-node err.type vs stripe-python error classes <span>— Vectle</span></a>