api_connection_errorcriticalAffects MRR

Stripe api_connection_error Error — Causes, Fix & MRR Impact

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.

What this means

Your server could not reach Stripe (network or DNS issue). Retry with backoff; use idempotency to avoid duplicate charges if the request actually succeeded.

Why it happens

Network failure

Temporary network issue between your server and Stripe (e.g. timeout, packet loss).

DNS or firewall

Your server cannot resolve api.stripe.com or outbound HTTPS to Stripe is blocked.

Stripe outage

Stripe or its infrastructure had an outage; check status.stripe.com.

TLS or certificate issue

TLS handshake or certificate validation failed (e.g. old client, proxy).

MRR Impact

Connection failures can block billing; retries with backoff and idempotency protect MRR.

Retries with idempotency are critical when connection errors occur to protect MRR.

Avg. recovery rate: High when retrying with backoff; many connection errors are transient.

Urgency: immediate

How to fix it

  1. 1

    Implement retry with exponential backoff

    When you get api_connection_error, retry the request after a delay (e.g. 1s, 2s, 4s). Use Idempotency-Key so duplicate requests do not create duplicate charges.

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

    Use Idempotency-Key

    Always use Idempotency-Key for payment-creating requests (PaymentIntent, Charge, etc.) so that retries after connection errors do not double-charge.

  3. 3

    Check Stripe status

    If connection errors persist, check status.stripe.com. If Stripe is healthy, check your network, DNS, and firewall for outbound HTTPS to api.stripe.com.

  4. 4

    Set timeouts

    Set reasonable timeouts on Stripe API calls so that hung connections do not block your process indefinitely. Retry after timeout.

  5. 5

    Monitor and alert

    Track api_connection_error rate; alert when it spikes so you can investigate network or Stripe issues.

Detect api_connection_error automatically

Alert on api_connection_error spikes; check Stripe status and your network.

Monitor your Stripe health free →

FAQ

What does Stripe api_connection_error mean?
api_connection_error means your server could not connect to Stripe's API (e.g. network failure, DNS, firewall, or Stripe outage). For SaaS, implement retries with backoff and idempotency; do not assume the payment failed—it may not have been received. Check Stripe status and your network.
Should I retry api_connection_error?
Yes. Connection errors are often temporary. Retry with exponential backoff. Use Idempotency-Key so that if the request actually reached Stripe and only the response was lost, you do not create duplicate charges. Monitor Stripe status page for outages.
How do I prevent api_connection_error?
Ensure your server can reach api.stripe.com (DNS, firewall, outbound HTTPS). Use a stable network and consider retries and timeouts. Check Stripe's status and SDK version for known issues.
Does api_connection_error affect MRR?
Yes. If billing or renewal requests fail due to connection errors and you do not retry, charges can be missed and MRR lost. Retries with idempotency protect MRR.

Related errors

api_error

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.

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