| [ Web Proxy ] |
| Viewing: https://docs.stripe.com/api/errors#errors-decline_code | [Back] [Original] |
Stripe uses conventional HTTP response codes to indicate the success or failure of an API request. In general:
2xx range indicate success.4xx range indicate an error that failed given the information provided. For example, an omitted required parameter, a failed charge, or a declined card.5xx range indicate an error with the Stripe servers (these are rare).For some errors that could be handled programmatically, a short string indicating the error code reported.
For card errors resulting from a card issuer decline, a short string indicating the card issuers reason for the decline if they provide one.
A human-readable message providing more details about the error. For card errors, these messages can be shown to your users.
If the error is parameter-specific, the parameter related to the error. For example, you can use this to display a message near the correct form field.
The PaymentIntent object for errors returned on a request involving a PaymentIntent.
The type of error returned. One of api_error, card_error, idempotency_error, or invalid_request_error
api_error |
card_error |
idempotency_error |
invalid_request_error |
| 200 | OK | Everything worked as expected. |
| 400 | Bad Request | The request was unacceptable, often due to missing a required parameter. |
| 401 | Unauthorized | No valid API key provided. |
| 402 | Request Failed | The parameters were valid but the request failed. |
| 403 | Forbidden | The API key doesnt have permissions to perform the request. |
| 404 | Not Found | The requested resource doesnt exist. |
| 409 | Conflict | The request conflicts with another request (perhaps due to using the same idempotent key). |
| 424 | External Dependency Failed | The request couldnt be completed due to a failure in a dependency external to Stripe. |
| 429 | Too Many Requests | Too many requests hit the API too quickly. We recommend an exponential backoff of your requests. |
| 500, 502, 503, 504 | Server Errors | Something went wrong on Stripes end. (These are rare.) |
api_error | API errors cover any other type of problem (e.g., a temporary problem with Stripes servers), and are extremely uncommon. |
card_error | Card errors are the most common type of error you should expect to handle. They result when the user enters a card that cant be charged for some reason. |
idempotency_error | Idempotency errors occur when an Idempotency-Key is re-used on a request that does not match the first requests API endpoint and parameters. |
invalid_request_error | Invalid request errors arise when your request has invalid parameters. |
Our Client libraries raise exceptions for many reasons, such as a failed charge, invalid parameters, authentication errors, and network unavailability. We recommend writing code that gracefully handles all possible API exceptions.
Many objects allow you to request additional information as an expanded response by using the expand request parameter. This parameter is available on all API requests, and applies to the response of that request only. You can expand responses in two ways.
In many cases, an object contains the ID of a related object in its response properties. For example, a Charge might have an associated Customer ID. You can expand these objects in line with the expand request parameter. The expandable label in this documentation indicates ID fields that you can expand into objects.
Some available fields arent included in the responses by default, such as the number and cvc fields for the Issuing Card object. You can request these fields as an expanded response by using the expand request parameter.
You can expand recursively by specifying nested fields after a dot (.). For example, requesting payment_intent.customer on a charge expands the payment_intent property into a full PaymentIntent object, then expands the customer property on that payment intent into a full Customer object.
You can use the expand parameter on any endpoint that returns expandable fields, including list, create, and update endpoints.
Expansions on list requests start with the data property. For example, you can expand data.customers on a request to list charges and associated customers. Performing deep expansions on numerous list requests might result in slower processing times.
Expansions have a maximum depth of four levels (for example, the deepest expansion allowed when listing charges is data.payment_intent.customer.default_source).
You can expand multiple objects at the same time by identifying multiple items in the expand array.
{ "id": "ch_3LmzzQ2eZvKYlo2C0XjzUzJV", "object": "charge", "customer": { "id": "cu_14HOpH2eZvKYlo2CxXIM7Pb2", "object": "customer", // ... }, "payment_intent": { "id": "pi_3MtwBwLkdIwHu7ix28a3tqPa", "object": "payment_intent", "customer": { "id": "cus_NffrFeUfNV2Hib", "object": "customer", // ... }, // ... }, // ...}| Web Proxy Viewer | New URL | Original Page |