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

# Errors

> Error response format and machine-readable codes

Flowlix uses conventional HTTP status codes: `2xx` means success, `4xx` means
a problem with the request, `5xx` means a problem on Flowlix's side. Every
error response carries a JSON body with a single `error` object:

```json theme={null}
{
  "error": {
    "code": "parameter_missing",
    "message": "The Idempotency-Key header is required for this request.",
    "param": "Idempotency-Key",
    "doc_url": "https://docs.flowlix.dev/guides/errors",
    "request_id": "req_abc123def456"
  }
}
```

| Field        | Description                                                                                              |
| ------------ | -------------------------------------------------------------------------------------------------------- |
| `code`       | Short machine-readable code identifying the exact problem.                                               |
| `message`    | Human-readable explanation. Safe to log; do not show raw to customers.                                   |
| `param`      | The request parameter that caused the error, when applicable (e.g. `billing_details[address][country]`). |
| `doc_url`    | Link to the relevant documentation.                                                                      |
| `request_id` | Matches the `Request-Id` response header. Include it when contacting support.                            |

<Note>
  **A declined card is not an HTTP error.** Card declines surface on the
  Payment object as `status: "FAILED"` with a `failure_code` — the create
  request itself still returns `201`. HTTP errors describe problems with the
  request or the operation's preconditions, not the issuer's decision. See
  [Payment lifecycle](/guides/payment-lifecycle).
</Note>

## Error codes

The `code` field pinpoints the exact problem. It is normally present; if it is
missing or unknown, branch on the HTTP status family.

| `code`                      | HTTP  | Meaning                                                                                                             |
| --------------------------- | ----- | ------------------------------------------------------------------------------------------------------------------- |
| `parameter_missing`         | `400` | A required field or header is absent. `param` names it.                                                             |
| `parameter_invalid`         | `400` | A field has the wrong format, type, or an out-of-range value. `param` names it.                                     |
| `request_body_invalid`      | `400` | The JSON body is malformed or cannot be parsed into the expected request shape.                                     |
| `object_not_found`          | `404` | No object with the supplied ID exists for this merchant and mode.                                                   |
| `invalid_search_criteria`   | `400` | Search or pagination parameters are not valid for the requested list operation.                                     |
| `object_state_conflict`     | `409` | The object exists, but its current state conflicts with the requested operation.                                    |
| `amount_exceeds_refundable` | `422` | The refund amount is greater than the payment's `amount_refundable`.                                                |
| `payment_not_refundable`    | `422` | The payment is not in a refundable state (for example, not `SUCCEEDED`).                                            |
| `invalid_api_key`           | `401` | The Bearer token is missing, malformed, expired, or revoked.                                                        |
| `mode_mismatch`             | `403` | The key's mode (test/live) does not match the resource.                                                             |
| `idempotency_key_reused`    | `409` | The key was already used with a different request body.                                                             |
| `idempotency_key_in_use`    | `409` | The original request with this key is still processing. Retry shortly.                                              |
| `internal_error`            | `500` | Unexpected error inside Flowlix. Safe to retry with the same idempotency key.                                       |
| `processing_error`          | `502` | A processing error occurred before Flowlix could complete the request. Safe to retry with the same idempotency key. |
| `service_unavailable`       | `503` | Flowlix is temporarily unable to process the request. Retry with backoff.                                           |

## Handling errors

```text theme={null}
4xx other than 409            → fix the request; do not blind-retry
409 idempotency_key_reused    → resend the original body, or use a new key
409 idempotency_key_in_use    → wait briefly, then retry the same body
5xx                           → retry with the same Idempotency-Key and exponential backoff
```

* Log `request_id` (or the `Request-Id` header) for every failed call — it is
  the fastest path to a support resolution.
* Treat unknown `code` values according to the HTTP status family; new codes
  may be added over time without notice.