Authentication

The Stripe API uses API keys to authenticate requests. You can view and manage your API keys in the Stripe Dashboard.

Test mode secret keys start with sk_test_ and have unrestricted access to their sandboxes. In live mode, you configure a restricted API key (starts with rk_live_) with specific API permissions. Using a restricted API key with only a subset of API permissions limits the damage a bad actor could cause if they obtained the key. In both test mode and live mode, you can create as many restricted API keys as you need for different use cases or components of your application. We also create a live mode secret key (starts with sk_live_) that grants access to all Stripe API resources. To protect your business, use restricted API keys instead.

Your API keys carry many privileges. Follow best practices to keep your keys safe. Don’t embed secret or restricted API keys in source code or client-side applications. Instead, use your server platform’s secrets vault to provide keys to your server-side applications. If your platform doesn’t offer a secrets vault, set your keys in environment variables.

The Stripe API authenticates requests using HTTP Basic Auth. Provide your API key as the basic auth username value. You don’t need to provide a password.

If you need to authenticate using bearer auth (for example, for a cross-origin request), use -H "Authorization: Bearer sk_test_BQok...gH4olfQ2sk_test_BQokikJOvBiI2HlWgH4olfQ2" instead of -u sk_test_BQok...gH4olfQ2sk_test_BQokikJOvBiI2HlWgH4olfQ2.

Make all API requests over HTTPS. Calls made over plain HTTP fail. API requests without authentication also fail.

Was this section helpful? Yes No

Authenticated Request

Your API Key

A sample test API key is included in all the examples here, so you can test any example right away. Do not submit any personally identifiable information in requests made with this key.

To test requests using your account, replace the sample API key with your actual API key or sign in.

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. For example, an omitted required parameter, a failed charge, or a declined card.
Many of these include an error code that briefly explains the error reported.
See Error handling for guidance.
Codes in the 5xx range indicate an error with the Stripe servers (these are rare).

Was this section helpful? Yes No

Attributes

code nullable string For some errors that could be handled programmatically, a short string indicating the error code reported.
decline _ code nullable 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.
message nullable string A human-readable message providing more details about the error. For card errors, these messages can be shown to your users.
param nullable 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 _ intent nullable object The PaymentIntent object for errors returned on a request involving a PaymentIntent.
type enum 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

advice _ code nullable string
charge nullable string
doc _ url nullable string
network _ advice _ code nullable string
network _ decline _ code nullable string
payment _ method nullable object
payment _ method _ type nullable string
request _ log _ url nullable string
setup _ intent nullable object
source nullable object

HTTP Status Code Summary

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).
424	External Dependency Failed	The request couldn’t 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 Stripe’s end. (These are rare.)

Error Types

`api_error`	API errors cover any other type of problem (e.g., a temporary problem with Stripe’s 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 can’t 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 request’s API endpoint and parameters.
`invalid_request_error`	Invalid request errors arise when your request has invalid parameters.

Handling errors

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

# Select a client library to see examples of# handling different kinds of errors.