Errors and retries
Stripe reports a failure with an HTTP status code and a JSON envelope. The status shows how the request failed. The envelope names the cause and, when one field is at fault, the parameter to change.
The error envelope
A failed request returns one error object. The fields present depend on the failure.
{
"error": {
"type": "card_error",
"code": "card_declined",
"decline_code": "insufficient_funds",
"message": "Your card has insufficient funds.",
"charge": "ch_3Rsx4dDtWMrPDtgt1",
"param": "",
"doc_url": "https://stripe.com/docs/error-codes/card-declined",
"request_log_url": "https://dashboard.stripe.com/test/logs/req_UQf6XBwBl9yk66"
}
}
| Field | Purpose |
|---|---|
type | The error family. Drives the handling branch. |
code | A short machine-readable cause, such as parameter_invalid_integer. |
decline_code | The issuer's reason for a card error, such as insufficient_funds. |
message | Human-readable text. Show it to support staff, not to customers. |
param | The request parameter at fault, when the failure traces to one field. |
charge | The charge ID for a card error, when a charge exists. |
doc_url | A page that explains the specific code. |
request_log_url | The request log entry in the Dashboard, with the full request and the response. |
Log the request_log_url with every failure. It gives the shortest path from a support ticket to the exact request that failed.
Error types
Four type values cover the platform.
type | Meaning | Retry |
|---|---|---|
invalid_request_error | A parameter is missing or malformed, the object doesn't exist, or the key lacks access. | No. Fix the request. |
card_error | The card issuer declined the charge, or the card needs authentication. | Depends on decline_code. |
idempotency_error | The caller reused the key with different parameters. | No. Use a new key. |
api_error | Stripe failed to process a valid request. | Yes, with backoff. |
Status codes
| Status | Typical type | Cause | Retry |
|---|---|---|---|
400 | invalid_request_error | Malformed parameter, missing required field, or an incompatible combination. | No |
401 | invalid_request_error | Key missing, revoked, or from another account. | No |
402 | card_error | Issuer declined the charge. | Depends on decline_code |
403 | invalid_request_error | Key lacks permission for the resource. | No |
404 | invalid_request_error | Object doesn't exist in this mode. | No |
409 | idempotency_error | A request with this key is still running. | Yes, after a pause |
429 | rate_limit_error | Key exceeded its request rate. | Yes, with backoff |
500 | api_error | Stripe hit an unexpected condition. | Yes, with backoff |
502 | api_error | An upstream service failed. | Yes, with backoff |
503 | api_error | Stripe is temporarily unavailable. | Yes, with backoff |
504 | api_error | The request timed out inside Stripe. | Yes, with backoff |
Decline codes
A card_error carries a decline_code that separates a permanent rejection from a temporary one.
decline_code | Meaning | Retry | Action |
|---|---|---|---|
insufficient_funds | The account can't cover the amount. | Yes, later | Ask the customer to try another card or wait. |
expired_card | The card passed its expiry date. | No | Collect a new card. |
incorrect_cvc | The card verification code, or CVC, doesn't match. | Once | Ask the customer for the code again. |
processing_error | The network couldn't process the charge. | Yes | Retry after a short delay. |
card_declined | The issuer declined without a specific reason. | No | Ask for another payment method. |
authentication_required | The issuer requires 3D Secure. | After authentication | Run the challenge, then confirm again. |
lost_card, stolen_card | The issuer blocked a reported card. | No | Don't retry. Send the case to your risk team. |
Retrying a hard decline produces another decline and can raise the account's decline ratio. Retry only the codes marked yes, and stop after the retry budget runs out.
Build a retry policy
Retry only failures that can succeed on a second attempt: 409, 429, and the 5xx family. Use exponential backoff with jitter, and cap the number of attempts.
const RETRYABLE = new Set([409, 429, 500, 502, 503, 504]);
async function requestWithRetry(url, options, attempts = 4) {
for (let attempt = 0; attempt < attempts; attempt++) {
const response = await fetch(url, options);
if (response.ok) return response;
if (!RETRYABLE.has(response.status) || attempt === attempts - 1) {
return response;
}
const base = 2 ** attempt * 500;
const delay = base + Math.random() * 250;
await new Promise((resolve) => setTimeout(resolve, delay));
}
}
The four attempts wait about 0.5, 1, and 2 seconds, plus jitter. That schedule recovers from a short outage without hammering the API.
Pair the policy with an idempotency key on every POST. Without the key, a retry after a timeout can duplicate the charge.
Read the response before you retry
A 429 includes headers that tell you when to try again. Read them instead of guessing.
| Header | Meaning |
|---|---|
Retry-After | Seconds to wait before the next attempt. |
Stripe-Rate-Limited-Reason | Which limit tripped, such as global-concurrency or endpoint-concurrency. |
A 429 on one endpoint often means too many concurrent requests, not too many total requests. Sending fewer parallel calls fixes it faster than lengthening the backoff.
Diagnose a failure
- Read
typeand branch on it. Acard_errorneeds a customer action. Anapi_errorneeds a retry. - Read
paramfor a400. Fix the named field instead of the whole request. - Read
request_log_url. Confirm the request reached Stripe and check the exact payload. - Check the mode. A
404on a valid object often means a live key read a test object. - Check the key. A
403points to a restricted key without permission.
Common mistakes
| Mistake | Consequence | Fix |
|---|---|---|
Retrying every 4xx | Duplicate declines, wasted quota | Retry only 409, 429, and 5xx. |
| Fixed 1-second backoff | Synchronized retries after an outage | Add jitter to every delay. |
| Retrying without a key | Duplicate charges | Send an Idempotency-Key on each POST. |
Showing message to customers | Confusing or leaking internal detail | Map decline_code to your own copy. |
Ignoring request_log_url | Slow debugging | Log the link with the error. |
Next steps
- Idempotent requests for safe retries on writes.
- Pagination and list endpoints for
429-free bulk reads. - API versioning and upgrades when a schema change breaks a call.