Errors

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. Provider HTTP errors are not forwarded as a general merchant retry policy. Flowlix first makes bounded retries where safe. Exhausted Direct Payment or Payout preparation can return a created object in FAILED with processor_unavailable or processor_error, not an issuer decline. Uncertain execution is reconciled against the existing order; a technical read outage alone does not establish failure. Branch on the returned object status separately from the public HTTP error envelope. See Payment lifecycle and Payouts.

Error response

{
  "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.

Required payment customer identity

Both Direct and Hosted Payment Page creates require merchant_customer_id. Missing and explicit-null values cannot be read as the required request shape and return:

{
  "error": {
    "code": "request_body_invalid",
    "message": "Request body is invalid.",
    "param": "merchant_customer_id",
    "doc_url": "https://docs.flowlix.eu/guides/errors",
    "request_id": "req_abc123def456"
  }
}

Empty, blank, longer-than-255-scalar, U+0000-containing, or ill-formed Unicode values return parameter_invalid:

{
  "error": {
    "code": "parameter_invalid",
    "message": "Request validation failed.",
    "param": "merchant_customer_id",
    "doc_url": "https://docs.flowlix.eu/guides/errors",
    "request_id": "req_abc123def456"
  }
}

Record the error code, parameter, and request ID for diagnostics. Do not log or attach the rejected customer identity itself.

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.

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: —

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

currency_not_supported · 422

Operations: POST /v1/payments, POST /v1/payments/hpp, POST /v1/refunds, POST /v1/payouts
When it occurs: A new Payment uses a well-formed currency outside the supported payment currencies; a new Refund refers to a Payment in another currency; or a Payout uses a currency outside its independent supported set.
Developer action: Choose a supported payment currency for a new Payment. For a new Refund, check that the source Payment uses a supported payment currency; changing the Refund request cannot change its currency. Check the Payout operation separately for Payout eligibility.
Retry: Do not retry unchanged.
Idempotency key: Use a new key for the changed body.
param: currency for Payment and Payout; payment_id for Refund.

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

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

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: —

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: —

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

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.

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.

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: —

method_not_allowed · 405

Operations: Every public API route
When it occurs: The path matches a public API route, but the HTTP method is not supported for it. The Allow header lists the supported methods.
Developer action: Use a method listed in Allow and the API reference.
Retry: No blind retry.
Idempotency key: Preserve the key only when correcting the method for the original operation with an equivalent effective request identity.
param: —

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.

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: —

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.

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.

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: —

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

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: —

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: —

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: —

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.

resource_not_found · 404

Operations: Unmatched route requests that reach the API application
When it occurs: The path does not match a public API route.
Developer action: Correct the 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: —

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: —

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

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. Likewise, TRACE and non-standard HTTP methods can be rejected before the API application with 405 or 400 and without the 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, 405, 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.

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.

Get started

Build with Flowlix

Handle failures

API reference

Error response

Required payment customer identity

Complete request-error catalogue

Fallback for an unknown code

​Error response

​Required payment customer identity

​Complete request-error catalogue

​Fallback for an unknown code

Error response

Required payment customer identity

Complete request-error catalogue

Fallback for an unknown code