Stripe uses conventional HTTP response codes to indicate the success or failure of an API request. In general: Codes in the 2xx
range indicate success. Codes in the 4xx
range indicate an error that failed given the information provided (e.g., a required parameter was omitted, a charge failed, etc.). Codes in the 5xx
range indicate an error with Stripe’s servers (these are rare).
Some 4xx
errors that could be handled programmatically (e.g., a card is declined) include an error code that briefly explains the error reported.
Attributes
- typeenum
The type of error returned. One of
api_
,error card_
,error idempotency_
, orerror invalid_
request_ error Possible enum valuesapi_
error card_
error idempotency_
error invalid_
request_ error - codenullable string
For some errors that could be handled programmatically, a short string indicating the error code reported.
- decline_
codenullable string For card errors resulting from a card issuer decline, a short string indicating the card issuer’s reason for the decline if they provide one.
- messagenullable string
A human-readable message providing more details about the error. For card errors, these messages can be shown to your users.
- paramnullable string
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.
- payment_
intentnullable object The PaymentIntent object for errors returned on a request involving a PaymentIntent.
More
- chargenullable string
- payment_
method_ typenullable string - doc_
urlnullable string - request_
log_ urlnullable string - setup_
intentnullable object - sourcenullable object
- payment_
methodnullable object
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 doesn’t have permissions to perform the request. |
404 | Not Found | The requested resource doesn’t exist. |
409 | Conflict | The request conflicts with another request (perhaps due to using the same idempotent key). |
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 Stripe’s end. (These are rare.) |
api_ | API errors cover any other type of problem (e.g., a temporary problem with Stripe’s servers), and are extremely uncommon. |
card_ | Card errors are the most common type of error you should expect to handle. They result when the user enters a card that can’t be charged for some reason. |
idempotency_ | Idempotency errors occur when an Idempotency-Key is re-used on a request that does not match the first request’s API endpoint and parameters. |
invalid_ | 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.
- Related guide: Error Handling
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 aren’t 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 invoice.
on a charge expands the invoice
property into a full Invoice object, then expands the subscription
property on that invoice into a full Subscription 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.
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.
).
You can expand multiple objects at the same time by identifying multiple items in the expand
array.
- Related guide: Expanding responses
- Related video: Expand
{ "id": "ch_3LmzzQ2eZvKYlo2C0XjzUzJV", "object": "charge", "customer": { "id": "cu_14HOpH2eZvKYlo2CxXIM7Pb2", "object": "customer", // ... }, "invoice": { "id": "in_1LmzzQ2eZvKYlo2CpyWn8szu", "object": "invoice", "subscription": { "id": "su_1LmzoG2eZvKYlo2Cpw6S7dAq", "object": "subscription", // ... }, // ... }, // ...}
The API supports idempotency for safely retrying requests without accidentally performing the same operation twice. When creating or updating an object, use an idempotency key. Then, if a connection error occurs, you can safely repeat the request without risk of creating a second object or performing the update twice.
To perform an idempotent request, provide an additional IdempotencyKey
element to the request options.
Stripe’s idempotency works by saving the resulting status code and body of the first request made for any given idempotency key, regardless of whether it succeeds or fails. Subsequent requests with the same key return the same result, including 500
errors.
A client generates an idempotency key, which is a unique key that the server uses to recognize subsequent retries of the same request. How you create unique keys is up to you, but we suggest using V4 UUIDs, or another random string with enough entropy to avoid collisions. Idempotency keys are up to 255 characters long.
You can remove keys from the system automatically after they’re at least 24 hours old. We generate a new request if a key is reused after the original is pruned. The idempotency layer compares incoming parameters to those of the original request and errors if they’re the same to prevent accidental misuse.
We save results only after the execution of an endpoint begins. If incoming parameters fail validation, or the request conflicts with another request that’s executing concurrently, we don’t save the idempotent result because no API endpoint initiates the execution. You can retry these requests. Learn more about when you can retry idempotent requests.
All POST
requests accept idempotency keys. Don’t send idempotency keys in GET
and DELETE
requests because it has no effect. These requests are idempotent by definition.
Updateable Stripe objects—including Account, Charge, Customer, PaymentIntent, Refund, Subscription, and Transfer have a metadata
parameter. You can use this parameter to attach key-value data to these Stripe objects.
You can specify up to 50 keys, with key names up to 40 characters long and values up to 500 characters long.
You can use metadata to store additional, structured information on an object. For example, you could store your user’s full name and corresponding unique identifier from your system on a Stripe Customer object. Stripe doesn’t use metadata—for example, we don’t use it to authorize or decline a charge and it won’t be seen by your users unless you choose to show it to them.
Some of the objects listed above also support a description
parameter. You can use the description
parameter to annotate a charge-for example, a human-readable description such as 2 shirts for test@example.
. Unlike metadata
, description
is a single string, which your users might see (for example, in email receipts Stripe sends on your behalf).
Don’t store any sensitive information (bank account numbers, card details, and so on) as metadata or in the description
parameter.
- Related guide: Metadata
Sample metadata use cases
- Link IDs: Attach your system’s unique IDs to a Stripe object to simplify lookups. For example, add your order number to a charge, your user ID to a customer or recipient, or a unique receipt number to a transfer.
- Refund papertrails: Store information about the reason for a refund and the individual responsible for its creation.
- Customer details: Annotate a customer by storing an internal ID for your future use.
{ "id": "cus_123456789", "object": "customer", "address": { "city": "city", "country": "US", "line1": "line 1", "line2": "line 2", "postal_code": "90210", "state": "CA" }, "balance": 0, "created": 1483565364, "currency": null, "default_source": null, "delinquent": false, "description": null, "discount": null, "email": null, "invoice_prefix": "C11F7E1", "invoice_settings": { "custom_fields": null, "default_payment_method": null, "footer": null, "rendering_options": null }, "livemode": false, "metadata": { "order_id": "6735" }, "name": null, "next_invoice_sequence": 1, "phone": null, "preferred_locales": [], "shipping": null, "tax_exempt": "none"}