> ## Documentation Index
> Fetch the complete documentation index at: https://docs.ionicfi.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Errors

> Error response shape, status codes, and payment decline details.

Errors return JSON with an `error` object.

```json theme={null}
{
  "error": {
    "code": "INVALID_REQUEST",
    "message": "request body is required"
  }
}
```

Payment errors can include additional decline fields.

```json theme={null}
{
  "error": {
    "code": "PAYMENT_DECLINED",
    "message": "payment was declined",
    "type": "card_error",
    "decline_code": "insufficient_funds",
    "decline_type": "authorization",
    "retryable": false
  }
}
```

## Status code map

| Status | Meaning                                                               |
| ------ | --------------------------------------------------------------------- |
| `400`  | Invalid request syntax, invalid parameters, or exceeded field limits. |
| `401`  | Invalid, revoked, or missing credentials.                             |
| `402`  | Payment declined or rejected.                                         |
| `403`  | Authenticated but not allowed.                                        |
| `404`  | Resource not found or not visible to this merchant.                   |
| `409`  | Duplicate, conflict, optimistic lock, or in-progress idempotency key. |
| `422`  | Valid request syntax, invalid business state.                         |
| `429`  | Rate limit exceeded.                                                  |
| `500`  | The API could not complete the request.                               |
| `502`  | The payment service could not complete the request.                   |
| `503`  | The service is temporarily unavailable.                               |
| `504`  | The payment result is unknown or the request timed out.               |

## Client behavior

* Retry network failures and retryable `5xx` operations with the same
  idempotency key only when the operation-specific documentation says that a
  retry is safe.
* Do not retry validation errors without changing the request.
* Do not retry payment declines blindly.
* Include `X-Request-ID` when contacting support.

<Warning>
  Terminal payment timeouts, `GATEWAY_UNCERTAIN`, and disconnected client
  sockets are not proof that a Sale failed. Do not create another Sale. Inspect
  the PaymentIntent and any known Terminal Payment, retain the original
  idempotency key, and follow the
  [terminal-specific recovery guidance](/guides/in-person-payments#handle-api-errors).
</Warning>