Errors

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:

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

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.

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

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.

Get started

Guides

Error handling

Payments API

Error codes

Handling errors

​Error codes

​Handling errors

Error codes

Handling errors