> ## Documentation Index
> Fetch the complete documentation index at: https://docs.payra.com/llms.txt
> Use this file to discover all available pages before exploring further.
# Errors
> The error format every endpoint shares.
Payra uses HTTP status codes to say whether a request succeeded. Any API response that is not `2xx` has this body:
```json theme={null}
{
"error": {
"type": "invalid_request_error",
"code": "parameter_invalid",
"message": "Too small: expected number to be >0",
"param": "amount",
"request_id": "8f0c2b1e-4a7d-4c1e-9b8a-2f6d3e5a1c90"
}
}
```
The category of error. One of the values in the table below.
A short, stable identifier for the specific error.
A human-readable explanation. It can change; do not match on it.
The request parameter the error relates to, when there is one.
The id of the request. Include it when you contact Payra support.
Every API response also carries a `Request-Id` header with the same id, except a [replay](/idempotency), whose body
keeps the original request's id.
## Error types
| HTTP | `type` | Common `code`s | What to do |
| ---- | ----------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| 400 | `invalid_request_error` | `parameter_invalid`, `idempotency_key_invalid`, `payment_method_session_inactive`, `payment_method_session_used`, `card_not_tokenized`, `bank_account_not_tokenized`, `ach_authorization_required`, `ach_terms_version_unsupported`, `payment_provider_not_configured`, `payment_method_unusable`, `webhook_endpoint_limit_reached`, `payment_not_refundable`, `refund_amount_exceeds_balance` | Fix the request. `param` names the field. `payment_method_session_inactive` on a session that has not been confirmed yet: let Elements confirm it, then retry with a new `Idempotency-Key`; an expired or canceled session, or one that succeeded more than 30 minutes ago, needs a new one. `payment_method_unusable`: the [payment method](/payment-methods) was already spent, expired, or detached from its customer; collect another. `card_not_tokenized` / `bank_account_not_tokenized`: card or account details reached the API in the clear; submit them through [Elements](/elements). `ach_authorization_required`: the bank account payment method carries no accepted ACH authorization; collect the account again through Elements. `ach_terms_version_unsupported`: the accepted text is a version this server no longer defines; reload Elements. `payment_provider_not_configured`: card payments, or ACH debits, are not set up for the workspace. `payment_not_refundable`: the payment is not `succeeded` (a bank debit still `processing`, say), or its processor transaction cannot be refunded. `refund_amount_exceeds_balance`: `amount` is more than what is left to [refund](/refunds); the message says how much. |
| 400 | `idempotency_error` | `idempotency_key_required`, `idempotency_key_reused` | `POST /payments` and `POST /refunds` need an `Idempotency-Key`; use a new one for a different request. |
| 400 | `card_error` | `card_expired` | The collected card's expiry month has passed. Collect another card. |
| 402 | `card_error` | `card_verification_failed`, `bank_account_verification_failed`, `card_declined`, `refund_failed` | The processor refused the card, the bank account, the charge or the refund. For a card or a bank account, collect the details again with a new session and retry; for a charge, `error.payment` names the failed [payment](/payments) and `error.decline_code` says why; for a refund, `error.refund` names the failed [refund](/refunds) and `error.failure_code` says why; refund again later with a new key. |
| 401 | `authentication_error` | `api_key_missing`, `invalid_api_key`, `publishable_key_not_allowed`, `api_key_environment_mismatch`, `client_secret_missing`, `invalid_client_secret` | Check the key and the `Authorization` header. A browser must send the session's `client_secret`. |
| 403 | `permission_error` | `insufficient_scope`, `developer_integrations_disabled`, `refunds_disabled` | Use a key with the scope, or ask Payra to enable the API. `refunds_disabled`: refunds are switched off for this workspace. |
| 404 | `invalid_request_error` | `resource_missing` | Check the URL or the object id. |
| 409 | `idempotency_error` | `idempotency_key_in_flight` | Retry shortly with the same key. |
| 409 | `api_error` | `conflict`, `refund_in_flight`, `checkout_session_payment_in_flight` | The object changed under the request, or a [webhook resend](/webhooks) named an endpoint whose earlier delivery is still being retried. If you sent an `Idempotency-Key`, the answer is stored under it, so read the object back first, then retry with a new key. `refund_in_flight`: a [refund](/refunds) of this payment is still `pending`; wait for it to succeed or fail before refunding again. `checkout_session_payment_in_flight`: the customer is paying on the [checkout page](/hosted-checkout) you tried to expire; retrieve the session once that payment is done. |
| 429 | `rate_limit_error` | `rate_limit_exceeded` | Wait `Retry-After` seconds, then retry. |
| 500 | `api_error` | `internal_error` | If you sent an `Idempotency-Key` on a `POST`, the `500` is stored under it: read the object back (retrieve or list) before retrying with a new key. Quote `request_id` to support. |
Handle errors by `type` and `code`, never by `message`.