Skip to main content
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": {
    "type": "invalid_request_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"
  }
}
FieldDescription
typeError category — the first thing to branch on.
codeShort machine-readable code identifying the exact problem.
messageHuman-readable explanation. Safe to log; do not show raw to customers.
paramThe request parameter that caused the error, when applicable (e.g. billing_details[address][country]).
decline_codeFor card_error only: the standardized decline reason. See Decline codes.
doc_urlLink to the relevant documentation.
request_idMatches 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 decline_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 types

error.typeTypical HTTPMeaning
invalid_request_error400, 404, 422The request is malformed, fails validation, references a missing resource, or is not allowed in the current state.
authentication_error401, 403The API key is missing, invalid, revoked, or not allowed to perform the operation.
idempotency_error409An Idempotency-Key was reused with a different body, or the original request is still in flight.
card_error422The operation cannot proceed for a card-related reason; decline_code carries the detail.
rate_limit_error429Too many requests. Honor the Retry-After header.
api_error500, 503Something went wrong on Flowlix’s side or at an upstream processor. Retry with the same idempotency key.

​
Error codes

The code field pinpoints the exact problem within a type:
codeTypeHTTPMeaning
parameter_missinginvalid_request_error400A required field or header is absent. param names it.
parameter_invalidinvalid_request_error400A field has the wrong format, type, or an out-of-range value. param names it.
resource_not_foundinvalid_request_error404No object with the supplied ID exists for this merchant and mode.
amount_exceeds_refundableinvalid_request_error422The refund amount is greater than the payment’s amount_refundable.
payment_not_refundableinvalid_request_error422The payment is not in a refundable state (for example, not SUCCEEDED).
invalid_api_keyauthentication_error401The Bearer token is missing, malformed, expired, or revoked.
mode_mismatchauthentication_error403The key’s mode (test/live) does not match the resource.
idempotency_key_reusedidempotency_error409The key was already used with a different request body.
idempotency_key_in_flightidempotency_error409The original request with this key is still processing. Retry shortly.
rate_limit_exceededrate_limit_error429Request rate exceeded for this API key.
internal_errorapi_error500Unexpected error inside Flowlix. Safe to retry with the same idempotency key.
service_unavailableapi_error503Flowlix or an upstream processor is temporarily unavailable. Retry with backoff.

​
Handling errors

4xx other than 409/429  → fix the request; do not blind-retry
409 idempotency_error   → resend the original body, or use a new key for a new operation
429 rate_limit_error    → wait Retry-After seconds, then retry with backoff
5xx api_error           → 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 as their type’s default behavior; new codes may be added over time without notice.

​
Rate limits

Rate limits are applied per API key. When you exceed them, requests fail with 429 rate_limit_error and a Retry-After header with the number of seconds to wait. Spread bursts, cache GET results where possible, and use webhooks instead of tight polling loops to stay well under the limits.