[metadata]
viewport: width=device-width, initial-scale=1.0, viewport-fit=cover

[document-links]
/api
API keys: /keys
Account Links v2: https://docs.stripe.com/api/v2/core/account-links
Account Links: https://docs.stripe.com/api/account_links
Account Sessions: https://docs.stripe.com/api/account_sessions
Account Tokens v2: https://docs.stripe.com/api/v2/core/account-tokens
Accounts v2: https://docs.stripe.com/api/v2/core/accounts
Accounts: https://docs.stripe.com/api/accounts
Alerts: https://docs.stripe.com/api/billing/alert
Application Fee Refunds: https://docs.stripe.com/api/fee_refunds
Application Fees: https://docs.stripe.com/api/application_fees
Authentication: /api/authentication
Authentication: https://docs.stripe.com/api/authentication
Balance Settings: https://docs.stripe.com/api/balance-settings
Balance Transactions: https://docs.stripe.com/api/balance_transactions
Balances: https://docs.stripe.com/api/balance
Bank Accounts: https://docs.stripe.com/api/customer_bank_accounts
Capabilities: https://docs.stripe.com/api/capabilities
Cards: https://docs.stripe.com/api/cards
Cash Balance Transactions: https://docs.stripe.com/api/cash_balance_transactions
Cash Balances: https://docs.stripe.com/api/cash_balance
Charges: https://docs.stripe.com/api/charges
Checkout Sessions: https://docs.stripe.com/api/checkout/sessions
Confirmation Tokens: https://docs.stripe.com/api/confirmation_tokens
Connected Accounts: https://docs.stripe.com/api/connected-accounts
Contact Sales: https://stripe.com/contact/sales
Contact Support: https://support.stripe.com/
Country Specs: https://docs.stripe.com/api/country_specs
Coupons: https://docs.stripe.com/api/coupons
Credit Balance Summaries: https://docs.stripe.com/api/billing/credit-balance-summary
Credit Balance Transactions: https://docs.stripe.com/api/billing/credit-balance-transaction
Credit Grants: https://docs.stripe.com/api/billing/credit-grant
Credit Notes: https://docs.stripe.com/api/credit_notes
Customer Balance Transactions: https://docs.stripe.com/api/customer_balance_transactions
Customer Portal Configurations: https://docs.stripe.com/api/customer_portal/configurations
Customer Portal Sessions: https://docs.stripe.com/api/customer_portal/sessions
Customer Sessions: https://docs.stripe.com/api/customer_sessions
Customers: https://docs.stripe.com/api/customers
Discord: https://stripe.com/go/developer-chat
Discounts: https://docs.stripe.com/api/discounts
Disputes: https://docs.stripe.com/api/disputes
Docs: /
Error Handling: /error-handling
Error handling: /error-handling
Errors: /api/errors
Errors: https://docs.stripe.com/api/errors
Event Destinations v2: https://docs.stripe.com/api/v2/core/event-destinations
Events v2: https://docs.stripe.com/api/v2/core/events
Events: https://docs.stripe.com/api/events
Expanding Responses: https://docs.stripe.com/api/expanding_objects
External Account Cards: https://docs.stripe.com/api/external_account_cards
External Bank Accounts: https://docs.stripe.com/api/external_accounts
File Links: https://docs.stripe.com/api/file_links
Files: https://docs.stripe.com/api/files
Financing Offers: https://docs.stripe.com/api/capital/financing_offers
Financing Summaries: https://docs.stripe.com/api/capital/financing_summary
HTTPS: http://en.wikipedia.org/wiki/HTTP_Secure
Handling errors: /api/errors/handling
Idempotent requests: https://docs.stripe.com/api/idempotent_requests
Include-dependent response values (API v2): https://docs.stripe.com/api/include_dependent_response_values
Introduction: https://docs.stripe.com/api
Invoice Items: https://docs.stripe.com/api/invoiceitems
Invoice Line Items: https://docs.stripe.com/api/invoice-line-item
Invoice Payments: https://docs.stripe.com/api/invoice-payment
Invoice Rendering Templates: https://docs.stripe.com/api/invoice-rendering-template
Invoices: https://docs.stripe.com/api/invoices
Login Links: https://docs.stripe.com/api/accounts/login_link
Mandates: https://docs.stripe.com/api/mandates
Markdoc: https://markdoc.dev
Metadata: https://docs.stripe.com/api/metadata
Meter Event Adjustment: https://docs.stripe.com/api/billing/meter-event-adjustment
Meter Event Adjustments v2: https://docs.stripe.com/api/v2/billing/meter-event-adjustments
Meter Event Streams v2: https://docs.stripe.com/api/v2/meter-event-streams
Meter Event Summary: https://docs.stripe.com/api/billing/meter-event-summary
Meter Events v2: https://docs.stripe.com/api/v2/meter-events
Meter Events: https://docs.stripe.com/api/billing/meter-event
Meters: https://docs.stripe.com/api/billing/meter
Pagination: https://docs.stripe.com/api/pagination
Payment Intents: https://docs.stripe.com/api/payment_intents
Payment Links: https://docs.stripe.com/api/payment-link
Payment Method Configurations: https://docs.stripe.com/api/payment_method_configurations
Payment Method Domains: https://docs.stripe.com/api/payment_method_domains
Payment Methods: https://docs.stripe.com/api/payment_methods
PaymentIntent object: /api/payment_intents/object
Payouts: https://docs.stripe.com/api/payouts
Person Tokens v2: https://docs.stripe.com/api/v2/core/person-tokens
Persons v2: https://docs.stripe.com/api/v2/core/persons
Persons: https://docs.stripe.com/api/persons
Plans: https://docs.stripe.com/api/plans
Prices: https://docs.stripe.com/api/prices
Products: https://docs.stripe.com/api/products
Promotion Codes: https://docs.stripe.com/api/promotion_codes
Quotes: https://docs.stripe.com/api/quotes
Read llms.txt: /llms.txt
Refunds: https://docs.stripe.com/api/refunds
Request IDs: https://docs.stripe.com/api/request_ids
Secrets: https://docs.stripe.com/api/secret_management
Setup Attempts: https://docs.stripe.com/api/setup_attempts
Setup Intents: https://docs.stripe.com/api/setup_intents
Shared Payment Granted Tokens: https://docs.stripe.com/api/shared-payment/granted-token
Shared Payment Issued Tokens: https://docs.stripe.com/api/shared-payment/issued-token
Shipping Rates: https://docs.stripe.com/api/shipping_rates
Sign in →: https://dashboard.stripe.com/login?redirect=https%3A%2F%2Fdocs.stripe.com%2Fapi%2Fauthentication
Sources: https://docs.stripe.com/api/sources
Stripe Balance Debit Agreements: https://docs.stripe.com/api/stripe_balance_debit_agreements
Subscription Items: https://docs.stripe.com/api/subscription_items
Subscription Schedules: https://docs.stripe.com/api/subscription_schedules
Subscriptions: https://docs.stripe.com/api/subscriptions
Support: https://support.stripe.com
Tax Codes: https://docs.stripe.com/api/tax_codes
Tax IDs: https://docs.stripe.com/api/tax_ids
Tax Rates: https://docs.stripe.com/api/tax_rates
Test Clocks: https://docs.stripe.com/api/test_clocks
Tokens: https://docs.stripe.com/api/tokens
Top-ups: https://docs.stripe.com/api/topups
Transfer Reversals: https://docs.stripe.com/api/transfer_reversals
Transfers: https://docs.stripe.com/api/transfers
Versioning: https://docs.stripe.com/api/versioning
best practices: /keys-best-practices
card issuer’s reason for the decline: /declines#issuer-declines
changelog: /changelog
declined: /declines
error code: /error-codes
restricted API key: /keys#create-restricted-api-key
sign in: https://dashboard.stripe.com/login?redirect=https%3A%2F%2Fdocs.stripe.com%2Fapi%2Fauthentication
the Stripe Dashboard: https://dashboard.stripe.com/login?redirect=/apikeys

[content]
Authentication | Stripe API Reference
Find anything
/
Ask AI
Introduction
Authentication
Errors
Expanding Responses
Idempotent requests
Include-dependent response values (API v2)
Metadata
Pagination
Request IDs
Connected Accounts
Versioning
Core Resources
Accounts
v2
Account Links
v2
Account Tokens
v2
Balances
Balance Transactions
Charges
Customers
Customer Sessions
Disputes
Events
Events
v2
Event Destinations
v2
Files
File Links
Mandates
Payment Intents
Persons
v2
Person Tokens
v2
Setup Intents
Setup Attempts
Stripe Balance Debit Agreements
Payouts
Refunds
Confirmation Tokens
Tokens
Payment Methods
Payment Methods
Payment Method Configurations
Payment Method Domains
Bank Accounts
Cash Balances
Cash Balance Transactions
Cards
Sources
Products
Products
Prices
Coupons
Promotion Codes
Discounts
Tax Codes
Tax Rates
Shipping Rates
Commerce
Agentic Commerce
Shared Payment Issued Tokens
Shared Payment Granted Tokens
Checkout
Checkout Sessions
Payment Links
Payment Links
Billing
Alerts
Credit Balance Summaries
Credit Balance Transactions
Credit Grants
Credit Notes
Customer Balance Transactions
Customer Portal Configurations
Customer Portal Sessions
Invoices
Invoice Items
Invoice Line Items
Invoice Payments
Invoice Rendering Templates
Meters
Meter Events
Meter Event Adjustment
Meter Event Adjustments
v2
Meter Event Streams
v2
Meter Event Summary
Meter Events
v2
Plans
Quotes
Subscriptions
Subscription Items
Subscription Schedules
Tax IDs
Test Clocks
Capital
Financing Offers
Financing Summaries
Connect
Accounts
Login Links
Account Links
Account Sessions
Application Fees
Application Fee Refunds
Capabilities
Country Specs
Balance Settings
External Bank Accounts
External Account Cards
Persons
Top-ups
Transfers
Transfer Reversals
Secrets
Reserves
Fraud
Issuing
Terminal
Treasury
Payment Records
Account Evaluation
Entitlements
Sigma
Reporting
Financial Connections
Tax
Identity
Crypto
Climate
Forwarding
Privacy
Webhooks
2026-07-29
.
dahlia
API Reference
Docs
Support
Sign in
→
Authentication
Ask about this section
Copy for LLM
View as Markdown
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.
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
curl
https://api.stripe.com/v1/charges \
-u
sk_test_wsFx86X...E4dMskBgJYrt
sk_test_wsFx86XDJWwmE4dMskBgJYrt
:
# The colon prevents curl from asking for a password.
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
Ask about this section
Copy for LLM
View as Markdown
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
More
Expand all
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
Ask about this section
Copy for LLM
View as Markdown
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.
Need help?
Contact Support
.
Chat with Stripe developers on
Discord
.
Check out our
changelog
.
Questions?
Contact Sales
.
LLM?
Read llms.txt
.
Powered by
Markdoc
