Core Resources
Payment Methods
Products
Checkout
Payment Links
Billing
Capital
Connect
Reserves
Fraud
Issuing
Terminal
Treasury
Entitlements
Sigma
Reporting
Financial Connections
Tax
Identity
Crypto
Climate
Forwarding
Privacy
Webhooks

Errors 

About the API
Errors

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

  • 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.

  • typeenum

    The type of error returned. One of api_error, card_error, idempotency_error, or invalid_request_error

    Possible enum values
    api_error
    card_error
    idempotency_error
    invalid_request_error

More

  • advice_codenullable string

    For card errors resulting from a card issuer decline, a short string indicating how to proceed with an error if they provide one.

  • chargenullable string

    For card errors, the ID of the failed charge.

  • doc_urlnullable string

    A URL to more information about the error code reported.

  • network_advice_codenullable string

    For card errors resulting from a card issuer decline, a 2 digit code which indicates the advice given to merchant by the card network on how to proceed with an error.

  • network_decline_codenullable string

    For payments declined by the network, an alphanumeric code which indicates the reason the payment failed.

  • payment_methodnullable object

    The PaymentMethod object for errors returned on a request involving a PaymentMethod.

  • payment_method_typenullable string

    If the error is specific to the type of payment method, the payment method type that had a problem. This field is only populated for invoice-related errors.

  • request_log_urlnullable string

    A URL to the request log entry in your dashboard.

  • setup_intentnullable object

    The SetupIntent object for errors returned on a request involving a SetupIntent.

  • sourcenullable object

    The source object for errors returned on a request involving a source.

HTTP Status Code Summary
200OKEverything worked as expected.
400Bad RequestThe request was unacceptable, often due to missing a required parameter.
401UnauthorizedNo valid API key provided.
402Request FailedThe parameters were valid but the request failed.
403ForbiddenThe API key doesn’t have permissions to perform the request.
404Not FoundThe requested resource doesn’t exist.
409ConflictThe request conflicts with another request (perhaps due to using the same idempotent key).
424External Dependency FailedThe request couldn’t be completed due to a failure in a dependency external to Stripe.
429Too Many RequestsToo many requests hit the API too quickly. We recommend an exponential backoff of your requests.
500, 502, 503, 504Server ErrorsSomething went wrong on Stripe’s end. (These are rare.)
Error Types
api_errorAPI errors cover any other type of problem (e.g., a temporary problem with Stripe’s servers), and are extremely uncommon.
card_errorCard 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_errorIdempotency 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_request_errorInvalid request errors arise when your request has invalid parameters.