Skip to main content

​
Rate Limits

The Flowlix API enforces rate limits to protect the platform and ensure fair usage across all merchants. Rate limits are applied per API key: each API key has its own independent counter, so a test key and a live key on the same merchant account each get their own budget.

​
Current limits

ScopeLimit
Per API key500 requests per minute (sandbox)
The limit is environment-configurable and may be tuned per environment as the platform matures. Inspect the X-RateLimit-Limit header on every authenticated response to see the value currently in effect for your key.

​
Window behavior

The rate limiter uses a fixed 60-second window per API key. The window starts when the first request lands and resets the next time a request arrives after 60 seconds have elapsed. Because the window is fixed (not sliding), a client that bursts traffic near a window boundary can briefly fit up to ~2× the per-window limit across the boundary. If you need a smoother rate, throttle on your side.

​
Rate limit headers

Successful responses from /v1/* endpoints include rate limit information:
HeaderDescription
X-RateLimit-LimitMaximum requests allowed per window (e.g. 500).
X-RateLimit-RemainingRequests remaining in the current window.
X-RateLimit-ResetUnix timestamp (seconds) when the current window resets.
Example headers on a normal response: 
HTTP/1.1 200 OK
X-RateLimit-Limit: 500
X-RateLimit-Remaining: 487
X-RateLimit-Reset: 1719792060
Rate limit headers are populated only on responses where authentication succeeds — i.e. 2xx, 4xx and 5xx responses from /v1/* paths after the API key has been validated. They are not present on 401 Unauthorized responses (the auth filter short-circuits before the rate limiter runs).

​
When you hit the limit

If you exceed the rate limit, the API returns 429 Too Many Requests with a Retry-After header: 
HTTP/1.1 429 Too Many Requests
Retry-After: 45
X-RateLimit-Limit: 500
X-RateLimit-Remaining: 0
X-RateLimit-Reset: 1719792060

{
  "error": {
    "type": "rate_limit_error",
    "code": "rate_limit_exceeded",
    "message": "Too many requests. Please retry after 45 seconds.",
    "param": null,
    "decline_code": null,
    "doc_url": "https://docs.flowlix.dev/api-reference/rate-limits",
    "request_id": "req_abc123def456"
  }
}

​
Retry strategy

When you receive a 429 response:
  1. Read the Retry-After header — it tells you how many seconds to wait.
  2. Wait the specified time before retrying.
  3. Use exponential backoff if Retry-After is not present: 1s, 2s, 4s, 8s (max 30s).
import time
import requests

def make_request_with_retry(url, headers, json=None, max_retries=3):
    for attempt in range(max_retries):
        response = requests.post(url, headers=headers, json=json)

        if response.status_code != 429:
            return response

        retry_after = int(response.headers.get("Retry-After", 2 ** attempt))
        print(f"Rate limited. Retrying in {retry_after}s...")
        time.sleep(retry_after)

    return response  # Return last response if all retries exhausted

​
Best practices

  • Monitor X-RateLimit-Remaining — if it drops below 10% of the limit, slow down your request rate.
  • Batch where possible — use limit=100 on list endpoints to reduce the number of API calls.
  • Don’t retry instantly on 429 — always respect the Retry-After header.
  • Spread requests evenly — avoid bursts of requests at the start of each minute, especially around window boundaries.
  • Poll polished: when polling GET /v1/payments/{id} for terminal status, use a 1–2 second interval with a max wait, not a tight loop.