Skip to main content

​
Errors

The Flowlix API uses conventional HTTP response codes and returns structured JSON error objects to help you diagnose and handle problems programmatically.

​
HTTP status codes

CodeMeaning
200OK — The request succeeded.
201Created — A new resource was created (e.g., a payment).
400Bad Request — The request was malformed or missing required parameters.
401Unauthorized — The API key is missing or invalid.
402Payment Required — The card was declined.
404Not Found — The requested resource does not exist.
409Conflict — Idempotency key was reused with different parameters.
422Unprocessable Entity — The request was well-formed but semantically invalid.
429Too Many Requests — Rate limit exceeded.
500Internal Server Error — Something went wrong on our end.

​
Error object structure

All errors follow the same shape: 
{
  "error": {
    "type": "invalid_request_error",
    "code": "parameter_missing",
    "message": "Required parameter `amount` is missing.",
    "param": "amount",
    "decline_code": null,
    "doc_url": "https://docs.flowlix.eu/api-reference/errors",
    "request_id": "req_abc123def456"
  }
}

​
Error fields

FieldTypeDescription
typestringThe category of error. See error types below.
codestring or nullA machine-readable code providing more detail.
messagestringA human-readable explanation of what went wrong.
paramstring or nullThe specific request parameter that caused the error.
decline_codestring or nullFor card errors, the reason the card was declined.
doc_urlstring or nullA link to the relevant documentation page.
request_idstringThe unique request ID for support reference.

​
Error types

TypeDescription
api_errorAn unexpected error on Flowlix’s servers. These are rare and should be retried.
authentication_errorThe API key is missing, invalid, or revoked.
card_errorThe card was declined. Check decline_code for the specific reason.
idempotency_errorAn idempotency key was reused with different request parameters.
invalid_request_errorThe request was malformed, missing a required parameter, or had an invalid value.
rate_limit_errorToo many requests in a short period. Back off and retry.

​
Common error codes

CodeTypeDescription
parameter_missinginvalid_request_errorA required parameter was not provided.
parameter_invalidinvalid_request_errorA parameter value is invalid (e.g., negative amount).
resource_missinginvalid_request_errorThe requested resource (e.g., payment ID) does not exist.
invalid_api_keyauthentication_errorThe API key is not valid.
card_declinedcard_errorThe card was declined by the issuer.
expired_cardcard_errorThe card has expired.
invalid_cvccard_errorThe CVC code is incorrect.
payment_already_refundedinvalid_request_errorThe payment has already been refunded.
idempotency_key_in_useidempotency_errorThe idempotency key was previously used with different parameters.
rate_limit_exceededrate_limit_errorToo many requests. Check the Retry-After header.

​
Handling errors in code

Here is a recommended pattern for handling Flowlix API errors: 
import requests

response = requests.post(
    "https://api.flowlix.eu/v1/payments",
    headers={"Authorization": "Bearer fl_test_sk_abc123"},
    json={"amount": 4999, "currency": "eur", "card": {...}}
)

if response.status_code == 201:
    payment = response.json()
    # Payment succeeded -- fulfill the order
elif response.status_code == 402:
    error = response.json()["error"]
    decline_code = error.get("decline_code")
    # Card was declined -- show a message to the customer
elif response.status_code == 401:
    # Authentication failed -- check your API key
elif response.status_code == 429:
    retry_after = int(response.headers.get("Retry-After", 30))
    # Back off and retry after `retry_after` seconds
elif response.status_code >= 500:
    # Flowlix server error -- retry with exponential backoff
else:
    error = response.json()["error"]
    # Other client error -- log and investigate

​
Decline codes

When error.type is card_error, the decline_code field tells you why the card was declined. Common decline codes:
Decline codeMeaning
insufficient_fundsThe card does not have enough funds.
do_not_honorThe issuer declined without a specific reason.
expired_cardThe card has expired.
generic_declineThe card was declined for an unspecified reason.
See the full Decline Codes Reference for details on each code, including customer-facing messages and merchant actions.

​
Tips

  • Always check error.type to determine how to handle the error.
  • Log request_id from every error response — you will need it if you contact support.
  • Use decline_code for card errors to show appropriate messages to customers.
  • Retry on api_error with exponential backoff (start at 1 second, max 30 seconds).
  • Respect Retry-After on rate limit errors instead of guessing a wait time.