DocsAPI ReferenceErrors & Testing
Errors & Testing
The Payments API uses one predictable error envelope everywhere, so a single error handler covers every endpoint.
The error envelope
Every error response
{
"error": {
"type": "card_error",
"code": "card_declined",
"message": "Your card was declined."
}
}type— the broad category (matches the HTTP status).code— a stable machine-readable identifier to branch on.message— human-readable and safe to show to customers.
Error reference
| HTTP | type | Typical codes |
|---|---|---|
| 400 | invalid_request_error | parameter_invalid, invalid_json, metadata_invalid, idempotency_key_invalid, session_expired, invalid_success_url, invalid_cancel_url, unsupported_test_card, price_inactive, price_mode_unsupported, currency_unsupported |
| 401 | authentication_error | missing_api_key, invalid_api_key, wrong_key_type, invalid_client_secret, environment_mismatch |
| 402 | card_error | card_declined, invalid_card_number, expired_card, invalid_cvc, processing_error |
| 404 | invalid_request_error | resource_missing |
| 409 | invalid_request_error | session_already_complete, session_payment_failed, order_already_processed, idempotency_key_reused |
| 415 | invalid_request_error | unsupported_media_type |
| 429 | rate_limit_error | rate_limited, too_many_attempts (honor Retry-After) |
| 500 | api_error | internal_error, payment_outcome_unknown, settlement_failed |
Errors worth handling explicitly
| Code | What to do |
|---|---|
card_declined | Terminal for the session — create a new session on your server before the customer retries (anti-card-testing behavior). |
invalid_card_number / expired_card / invalid_cvc | Rejected before any charge — the session stays payable; let the customer fix the field and resubmit. |
session_expired | Create a new session. |
too_many_attempts / rate_limited | Back off for the number of seconds in the Retry-After header. |
payment_outcome_unknown / settlement_failed | The card may already be charged and we could not confirm the outcome automatically. Do NOT retry or create a new session — contact support with the session id for manual reconciliation. |
| Network failure after submitting a confirm | The payment may have gone through. Do NOT create a new session immediately — first retrieve the old one and check payment_status, or you risk charging twice. |
Test cards
In test mode (sk_test_ / pk_test_ keys) no real money moves. Two card numbers control the outcome:
| Card | Result |
|---|---|
4242 4242 4242 4242 | Approved |
4343 4343 4343 4343 | Declined (terminal card_declined) |
Any other number returns unsupported_test_card without consuming the session. Use any future expiry date and any CVC.
Environment isolation
Test keys only operate on your TEST store, live keys only on your LIVE store — mixing them returns
environment_mismatch. A key only sees its own store's products and sessions.