api_errorcriticalAffects MRR

Stripe api_error Error — Causes, Fix & MRR Impact

The Stripe api_error error occurs when Stripe's servers encounter an error (HTTP 5xx), causing the request to fail and potential MRR loss for SaaS businesses processing subscription payments.

What this means

Stripe's servers had an error. Retry with backoff; use Idempotency-Key to avoid duplicate charges if the first request actually succeeded.

Why it happens

Stripe server failure

An internal error on Stripe's side (e.g. timeout, crash). Stripe monitors and fixes these.

Timeout or overload

Stripe's server timed out or was temporarily overloaded.

Dependency failure

A service Stripe depends on (e.g. database, network) failed; Stripe returns 5xx.

Transient bug

A rare transient bug on Stripe's side; retry often succeeds.

MRR Impact

5xx errors can block billing; retries with idempotency protect MRR and prevent duplicate charges.

Retries with idempotency are essential for 5xx errors to protect MRR and avoid duplicates.

Avg. recovery rate: High when retrying with backoff; many 5xx are transient.

Urgency: immediate

How to fix it

  1. 1

    Retry with exponential backoff

    On HTTP 5xx or api_error, retry after 1s, 2s, 4s, 8s (cap at e.g. 60s). Do not retry in a tight loop.

    if (err.type === 'StripeAPIError') { await sleep(Math.min(1000 * Math.pow(2, attempt), 60000)); return retry(); }
  2. 2

    Use Idempotency-Key for payment requests

    For PaymentIntent create, Charge create, Subscription create, etc., always send Idempotency-Key. On retry, use the same key so Stripe returns the original result if the first request succeeded.

  3. 3

    Do not assume failure

    When you get 5xx, the request may have been processed. Do not show 'payment failed' to the customer until you have retried and confirmed failure, or you have checked the payment status.

  4. 4

    Check Stripe status

    If api_error persists, check status.stripe.com. If there is an incident, wait and retry. Contact Stripe support if the error is consistent.

  5. 5

    Monitor and alert

    Track api_error rate; alert on spikes. Correlate with Stripe status and your request patterns.

Detect api_error automatically

Alert on api_error or 5xx rate; check Stripe status and retry logic.

Monitor your Stripe health free →

FAQ

What does Stripe api_error mean?
api_error means something went wrong on Stripe's servers (HTTP 5xx). These are rare. For SaaS, retry with exponential backoff and Idempotency-Key. Do not assume the payment failed—it may have been processed. Check Stripe status and retry; if it persists, contact Stripe support.
Should I retry api_error?
Yes. Retry with backoff (e.g. 1s, 2s, 4s, 8s). Use the same Idempotency-Key so you do not create duplicate charges if the first request actually succeeded. Stripe recommends exponential backoff for 5xx errors.
How do I avoid duplicate charges on retry?
Always send an Idempotency-Key when creating payments (PaymentIntent, Charge, etc.). If the first request succeeded but returned 5xx, the retry with the same key returns the same result without creating a second charge.
Does api_error affect MRR?
Yes. If you do not retry, legitimate charges can fail and MRR can be lost. Retries with idempotency protect MRR and avoid duplicates.

Related errors

api_connection_error

The Stripe api_connection_error error occurs when your server cannot connect to Stripe's API (e.g. network or DNS failure), causing requests to fail and potential MRR loss for SaaS businesses processing subscription payments.

Affects MRRprocessing_error

The Stripe processing_error error occurs when an error happened while processing the card (e.g. issuer or network issue), causing the charge to fail and MRR risk for SaaS businesses processing subscription payments.

Affects MRR