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

# Errors

> Handle every public HTTP error by code, operation, and retry policy

Flowlix uses HTTP status codes for request outcomes. A `2xx` response contains
an operation result. A `4xx` response requires a merchant-side decision or
correction. For a retryable `5xx` response, use backoff and the original
idempotency key; follow the operation-specific retry rules below.

## Error response

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

| Field        | How to use it                                                                                                                                                              |
| ------------ | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `code`       | Stable machine-readable reason. Use this for branching.                                                                                                                    |
| `message`    | Diagnostic context that may include object-specific values and may change. Do not branch on it or show it directly to customers; apply normal redaction before logging it. |
| `param`      | Field, header, path, or query parameter involved, when one is available.                                                                                                   |
| `doc_url`    | Optional informational link to error documentation. Do not use it for branching.                                                                                           |
| `request_id` | Correlation ID matching the `Request-Id` header. Retain it for support.                                                                                                    |

## Complete request-error catalogue

The **Operations** field is the exact scope in which the code can be returned.
“Create operations” means the four authenticated `POST` routes documented
below. Open a case to see its cause, correction, retry rule, idempotency rule,
and `param` value together.

<AccordionGroup>
  <Accordion title="actor_forbidden · 403">
    * **Operations:** `POST /v1/refunds`
    * **When it occurs:** The supplied API key is not allowed to create Refunds.
    * **Developer action:** Verify that the key belongs to the intended merchant and mode. If it does, contact Flowlix to enable Refund access.
    * **Retry:** Retry only after access is corrected.
    * **Idempotency key:** Preserve the key when retrying the original Refund operation.
    * **`param`:** —
  </Accordion>

  <Accordion title="amount_exceeds_refundable · 422">
    * **Operations:** `POST /v1/refunds`
    * **When it occurs:** `amount` is greater than the succeeded parent Payment's latest `amount_refundable`. A zero remaining amount also gives `amount_exceeds_refundable` for any valid positive Refund amount.
    * **Developer action:** Retrieve the Payment and choose an allowed amount.
    * **Retry:** Retry only after correction.
    * **Idempotency key:** Use a new key for the corrected body.
    * **`param`:** `amount`
  </Accordion>

  <Accordion title="currency_not_supported · 422">
    * **Operations:** `POST /v1/payments`, `POST /v1/payments/hpp`, `POST /v1/payouts`
    * **When it occurs:** The well-formed currency is not accepted for a new Payment or Payout.
    * **Developer action:** Choose a supported currency before creating the object.
    * **Retry:** Do not retry unchanged.
    * **Idempotency key:** Use a new key for the changed body.
    * **`param`:** `currency`
  </Accordion>

  <Accordion title="idempotency_key_in_use · 409">
    * **Operations:** All create operations
    * **When it occurs:** The first request with this key is still being processed.
    * **Developer action:** Wait briefly for the original request.
    * **Retry:** Retry the original operation; card-data POST retries follow the PCI-safe recipe.
    * **Idempotency key:** Preserve the same key.
    * **`param`:** `Idempotency-Key`
  </Accordion>

  <Accordion title="idempotency_key_reused · 409">
    * **Operations:** All create operations
    * **When it occurs:** The same key was paired with a different idempotency identity. For Direct Payment, card fields are excluded and the conflict is based on non-card fields.
    * **Developer action:** Retry the original operation, or deliberately start a new one. Never persist a Direct card body for comparison.
    * **Retry:** Do not retry a conflicting identity unchanged.
    * **Idempotency key:** The original operation keeps the key; a new operation or card attempt gets a new key.
    * **`param`:** `Idempotency-Key`
  </Accordion>

  <Accordion title="internal_error · 500">
    * **Operations:** All authenticated operations
    * **When it occurs:** Flowlix encountered an unexpected error before returning a successful operation response.
    * **Developer action:** Retain `request_id` and use backoff.
    * **Retry:** Yes, for a transient failure; card-data POST retries follow the PCI-safe recipe.
    * **Idempotency key:** Preserve the original key.
    * **`param`:** —
  </Accordion>

  <Accordion title="invalid_api_key · 401">
    * **Operations:** All authenticated operations
    * **When it occurs:** The Bearer token is missing, malformed, invalid, expired, or revoked.
    * **Developer action:** Send a valid secret key for the intended merchant and mode from your server.
    * **Retry:** Retry only after fixing authentication.
    * **Idempotency key:** Preserve only when using the same API-key scope.
    * **`param`:** —
  </Accordion>

  <Accordion title="invalid_card · 422">
    * **Operations:** `POST /v1/payouts`
    * **When it occurs:** The destination card number fails validation.
    * **Developer action:** Correct `destination.card_number`.
    * **Retry:** No retry with the unchanged card.
    * **Idempotency key:** Use a new key for a corrected new body.
    * **`param`:** `destination.card_number`
  </Accordion>

  <Accordion title="invalid_request · 400">
    * **Operations:** `GET /v1/payments`, `GET /v1/payments/{id}`, `GET /v1/payouts`, `GET /v1/payouts/{payout_id}`
    * **When it occurs:** A read request contains an invalid path or query value.
    * **Developer action:** Correct the path or query parameters using the API reference.
    * **Retry:** Retry after correction.
    * **Idempotency key:** Not applicable.
    * **`param`:** The invalid value when available.
  </Accordion>

  <Accordion title="invalid_search_criteria · 400">
    * **Operations:** `GET /v1/payments`, `GET /v1/payouts`
    * **When it occurs:** A list filter, search value, cursor, or pagination combination is invalid.
    * **Developer action:** Correct the query parameters using the API reference.
    * **Retry:** Retry after correction.
    * **Idempotency key:** Not applicable.
    * **`param`:** The invalid query parameter when available.
  </Accordion>

  <Accordion title="merchant_not_provisioned · 422">
    * **Operations:** `POST /v1/payments`, `POST /v1/payments/hpp`, `POST /v1/refunds`, `POST /v1/payouts`
    * **When it occurs:** The merchant is not ready to use the requested operation.
    * **Developer action:** Contact Flowlix to complete provisioning for the intended mode before submitting another Payment, Refund, or Payout.
    * **Retry:** Retry only after provisioning is corrected.
    * **Idempotency key:** Preserve the key for the same operation; Direct retries still follow the PCI-safe recipe.
    * **`param`:** —
  </Accordion>

  <Accordion title="object_not_found · 404">
    * **Operations:** `POST /v1/payments`, `GET /v1/payments/{id}`, `POST /v1/refunds`, `POST /v1/payouts`, `GET /v1/payouts/{payout_id}`
    * **When it occurs:** A referenced or newly registered object cannot be found in the authenticated merchant and mode scope while the operation is being completed.
    * **Developer action:** Retain `request_id`; verify any supplied object ID, merchant, and mode. An object from another mode is not visible to the current key.
    * **Retry:** Do not blind retry.
    * **Idempotency key:** A corrected Refund `payment_id` needs a new key; otherwise preserve the original operation identity.
    * **`param`:** The object ID when available.
  </Accordion>

  <Accordion title="object_state_conflict · 409">
    * **Operations:** `POST /v1/payments`, `POST /v1/payouts`
    * **When it occurs:** The newly registered Direct Payment or Payout state conflicts with the provider update being completed.
    * **Developer action:** Retain `request_id` and the returned public object ID when one is available; contact support before starting another operation.
    * **Retry:** Do not blind retry.
    * **Idempotency key:** Preserve the original key for the same effective request identity; a new business operation needs a new key.
    * **`param`:** —
  </Accordion>

  <Accordion title="parameter_invalid · 400">
    * **Operations:** All authenticated operations
    * **When it occurs:** A field, header, path parameter, or query parameter has an invalid type, format, or range.
    * **Developer action:** Correct the parameter named by `param`.
    * **Retry:** Retry after correction.
    * **Idempotency key:** Use a new key when correcting a POST body.
    * **`param`:** The invalid parameter when available.
  </Accordion>

  <Accordion title="parameter_missing · 400">
    * **Operations:** All create operations
    * **When it occurs:** A required header is absent. Missing or null body fields are reported as `request_body_invalid`.
    * **Developer action:** Add the header named by `param`.
    * **Retry:** Retry after correction.
    * **Idempotency key:** Preserve the supplied key when one exists; use a new key if the effective POST body changes.
    * **`param`:** The missing header.
  </Accordion>

  <Accordion title="payment_acceptance_unavailable · 403">
    * **Operations:** `POST /v1/payments`, `POST /v1/payments/hpp`
    * **When it occurs:** The merchant cannot currently accept new Payments.
    * **Developer action:** Contact Flowlix to restore Payment acceptance before creating another Payment.
    * **Retry:** Retry only after access is restored.
    * **Idempotency key:** Preserve the key for the same attempt; Direct retries still follow the PCI-safe recipe.
    * **`param`:** —
  </Accordion>

  <Accordion title="payment_not_refundable · 422">
    * **Operations:** `POST /v1/refunds`
    * **When it occurs:** The parent Payment's status is not `SUCCEEDED`.
    * **Developer action:** Retrieve the Payment and stop unless later business state permits a Refund.
    * **Retry:** Do not retry unchanged.
    * **Idempotency key:** Use a new key for a later distinct Refund decision.
    * **`param`:** `payment_id`
  </Accordion>

  <Accordion title="payout_submission_unavailable · 403">
    * **Operations:** `POST /v1/payouts`
    * **When it occurs:** The merchant cannot currently submit new Payouts.
    * **Developer action:** Contact Flowlix to restore Payout access before creating another Payout.
    * **Retry:** Retry only after access is restored.
    * **Idempotency key:** Preserve the key for the original Payout with an equivalent effective request identity.
    * **`param`:** —
  </Accordion>

  <Accordion title="processing_error · 502">
    * **Operations:** `POST /v1/payments`
    * **When it occurs:** Flowlix could not validate a safe Direct Payment provider response.
    * **Developer action:** Retain `request_id` and retry from the same PCI-safe attempt with backoff.
    * **Retry:** Yes, while the original request remains available inside the PCI boundary.
    * **Idempotency key:** Preserve the same key.
    * **`param`:** —
  </Accordion>

  <Accordion title="rate_limit_exceeded · 429">
    * **Operations:** `POST /v1/payments`
    * **When it occurs:** The Direct Payment provider returned `429` for the submission.
    * **Developer action:** Wait for `Retry-After` when present, otherwise use exponential backoff.
    * **Retry:** Retry from the same PCI-safe attempt.
    * **Idempotency key:** Preserve the same key.
    * **`param`:** —
  </Accordion>

  <Accordion title="request_body_invalid · 400">
    * **Operations:** All create operations
    * **When it occurs:** JSON is malformed, has the wrong media type, or cannot be read as the request schema.
    * **Developer action:** Correct the JSON and `Content-Type`.
    * **Retry:** Retry after correction.
    * **Idempotency key:** Use a new key if the effective body changes.
    * **`param`:** The unreadable body field when available.
  </Accordion>

  <Accordion title="resource_not_found · 404">
    * **Operations:** Unmatched route requests that reach the API application
    * **When it occurs:** The HTTP method or path does not match a public API route.
    * **Developer action:** Correct the method or path using the API reference.
    * **Retry:** No blind retry.
    * **Idempotency key:** Preserve the key only when correcting the path for the original operation with an equivalent effective request identity.
    * **`param`:** —
  </Accordion>

  <Accordion title="service_unavailable · 503">
    * **Operations:** All authenticated operations
    * **When it occurs:** Flowlix or a required payment service is temporarily unavailable.
    * **Developer action:** Wait for `Retry-After` when present, then back off.
    * **Retry:** Yes; card-data POST retries follow the PCI-safe recipe.
    * **Idempotency key:** Preserve the original key.
    * **`param`:** —
  </Accordion>

  <Accordion title="unsupported_card · 422">
    * **Operations:** `POST /v1/payouts`
    * **When it occurs:** The destination card is not eligible for Payouts.
    * **Developer action:** Ask for another eligible card.
    * **Retry:** No retry with the unchanged card.
    * **Idempotency key:** Use a new key and body for another card.
    * **`param`:** `destination.card_number`
  </Accordion>
</AccordionGroup>

An unmatched request can be rejected earlier by an edge or router with HTTP
`404` and without the Flowlix API error envelope. Branch on the HTTP 404 status
first; use `error.code` only when the response contains the documented
envelope.

## Fallback for an unknown code

New codes may appear without breaking the response schema. If `code` is absent
or unknown, retain the HTTP status, `request_id`, code, and a safely redacted
message for diagnostics, then branch on the HTTP status:

* `400`, `401`, `403`, `404`, or `422`: inspect and correct the request or
  merchant-side precondition; do not blind retry.
* `409`: retrieve related objects and inspect idempotency state before retrying.
* `429`: wait for `Retry-After` or use exponential backoff.
* `500`, `502`, or `503`: preserve the original key and use exponential
  backoff. For Direct Payment and Payout, follow the PCI-safe card-data retry
  recipe instead of persisting the body.

Always log `request_id` or the `Request-Id` response header. Do not log secret
keys or unmasked card data.

<Note>
  A successful create response may still contain an object in a failed state.
  That is an operation failure, not an HTTP error. See
  [Operation failures](/guides/operation-failures).
</Note>