Skip to main content

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"
}
}
FieldPurpose
typeThe error family. Drives the handling branch.
codeA short machine-readable cause, such as parameter_invalid_integer.
decline_codeThe issuer's reason for a card error, such as insufficient_funds.
messageHuman-readable text. Show it to support staff, not to customers.
paramThe request parameter at fault, when the failure traces to one field.
chargeThe charge ID for a card error, when a charge exists.
doc_urlA page that explains the specific code.
request_log_urlThe request log entry in the Dashboard, with the full request and the response.
note

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.

typeMeaningRetry
invalid_request_errorA parameter is missing or malformed, the object doesn't exist, or the key lacks access.No. Fix the request.
card_errorThe card issuer declined the charge, or the card needs authentication.Depends on decline_code.
idempotency_errorThe caller reused the key with different parameters.No. Use a new key.
api_errorStripe failed to process a valid request.Yes, with backoff.

Status codes​

StatusTypical typeCauseRetry
400invalid_request_errorMalformed parameter, missing required field, or an incompatible combination.No
401invalid_request_errorKey missing, revoked, or from another account.No
402card_errorIssuer declined the charge.Depends on decline_code
403invalid_request_errorKey lacks permission for the resource.No
404invalid_request_errorObject doesn't exist in this mode.No
409idempotency_errorA request with this key is still running.Yes, after a pause
429rate_limit_errorKey exceeded its request rate.Yes, with backoff
500api_errorStripe hit an unexpected condition.Yes, with backoff
502api_errorAn upstream service failed.Yes, with backoff
503api_errorStripe is temporarily unavailable.Yes, with backoff
504api_errorThe 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_codeMeaningRetryAction
insufficient_fundsThe account can't cover the amount.Yes, laterAsk the customer to try another card or wait.
expired_cardThe card passed its expiry date.NoCollect a new card.
incorrect_cvcThe card verification code, or CVC, doesn't match.OnceAsk the customer for the code again.
processing_errorThe network couldn't process the charge.YesRetry after a short delay.
card_declinedThe issuer declined without a specific reason.NoAsk for another payment method.
authentication_requiredThe issuer requires 3D Secure.After authenticationRun the challenge, then confirm again.
lost_card, stolen_cardThe issuer blocked a reported card.NoDon't retry. Send the case to your risk team.
warning

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.

Node.js
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.

HeaderMeaning
Retry-AfterSeconds to wait before the next attempt.
Stripe-Rate-Limited-ReasonWhich 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​

  1. Read type and branch on it. A card_error needs a customer action. An api_error needs a retry.
  2. Read param for a 400. Fix the named field instead of the whole request.
  3. Read request_log_url. Confirm the request reached Stripe and check the exact payload.
  4. Check the mode. A 404 on a valid object often means a live key read a test object.
  5. Check the key. A 403 points to a restricted key without permission.

Common mistakes​

MistakeConsequenceFix
Retrying every 4xxDuplicate declines, wasted quotaRetry only 409, 429, and 5xx.
Fixed 1-second backoffSynchronized retries after an outageAdd jitter to every delay.
Retrying without a keyDuplicate chargesSend an Idempotency-Key on each POST.
Showing message to customersConfusing or leaking internal detailMap decline_code to your own copy.
Ignoring request_log_urlSlow debuggingLog the link with the error.

Next steps​