Networks aren't perfect. When a request times out, you don't know whether it reached us and already caused costs. An Idempotency-Key lets you repeat it safely. On top of that, headers tell you how many requests you can still send and how long you should wait. Here's how to use both for robust retry logic.
What an Idempotency-Key does
For a write request (POST, PUT, PATCH, DELETE), you send the Idempotency-Key header with a value you generate for this one operation. If you later send exactly the same request with the same key again, we don't run it a second time. If the first request completed successfully, you get its stored response back with no new costs.
curl https://api.flowmodels.one/v1/chat/completions \
-H "Authorization: Bearer at_your_key" \
-H "Content-Type: application/json" \
-H "Idempotency-Key: order-58213-summary" \
-d '{"model": "groq/openai/gpt-oss-120b", "messages": [{"role": "user", "content": "Summarize order 58213."}]}'
The key is 1 to 128 characters long and consists of letters, digits, periods, underscores and hyphens. A UUID always works. By default, we keep the stored response available for 24 hours.
A replayed response carries the header Idempotent-Replay: true. The body contains the flowai_request_id of the first request, and the x-request-id header contains the identifier of the current retry.
The three rules for the key
- One key per operation, not per attempt. Generate the key before you send for the first time and use it for all retries of that operation.
- Don't switch to a new key after a dropped connection. The first request may already have been processed and billed. A new key would run it a second time.
- Changed request, new key. If you send different content or a different filename with the same key, the API responds with
422 idempotency_key_reuse.
If the first request is still running, or its result isn't reliably known after a disruption, you immediately get 409 idempotency_key_in_progress. In that case, wait briefly and retry with the same key.
An Idempotency-Key only works with JSON and multipart requests. Any other Content-Type returns 415 invalid_content_type.
Reading the rate limit headers
Every response that was counted against your request limit carries these headers:
x-ratelimit-limit-requests: how many requests you can send per minutex-ratelimit-remaining-requests: how many of those are leftx-ratelimit-reset-requests: when the quota is full again, for example0sor1m30s
For rejections due to credit, spending limit or too many concurrent requests, these headers are missing, because the per-minute limit isn't the reason there. Request limit: how the tiers work explains how the tiers work.
What you can retry automatically
| Response | Retry automatically? |
|---|---|
429 rate_limit_exceeded |
yes, after the wait time from Retry-After |
429 concurrent_requests_exceeded |
yes, after Retry-After, and send fewer requests in parallel |
502, 503 provider_overloaded, 503 routing_unavailable |
yes, after Retry-After or with an increasing wait time |
409 idempotency_key_in_progress |
yes, wait briefly, same key |
429 insufficient_quota, 429 spend_limit_exceeded |
no, change the credit or limit first |
400, 401, 403, 404, 422 |
no, correct the request first |
Requests rejected with 429 cost nothing and leave no stored idempotency entry.
An example in Python
import time, uuid, requests
URL = "https://api.flowmodels.one/v1/chat/completions"
RETRYABLE = {"rate_limit_exceeded", "concurrent_requests_exceeded", "idempotency_key_in_progress"}
def error_code(response):
try:
return (response.json().get("error") or {}).get("code")
except ValueError:
return None
def send_request(payload):
key = str(uuid.uuid4()) # once per operation, the same for all attempts
for attempt in range(5):
try:
response = requests.post(
URL,
headers={"Authorization": "Bearer at_your_key", "Idempotency-Key": key},
json=payload,
timeout=120,
)
except requests.exceptions.RequestException:
time.sleep(2 ** attempt) # timeout: send again with the same key
continue
if response.status_code < 400:
return response.json()
if response.status_code in (502, 503) or error_code(response) in RETRYABLE:
time.sleep(int(response.headers.get("Retry-After", 2 ** attempt)))
continue
response.raise_for_status() # don't retry anything else
raise RuntimeError("FlowModels not reachable after 5 attempts")
A timeout on your side is treated here like a temporary disruption: the request goes out again with the same key. If the first one already succeeded, you get its response with no new costs.
Good to know
- Every response carries the
x-request-idheader, including error responses. Write it to your logs. Support can use it to find a request right away. - A dropped stream can't be resumed. For long responses, a background job is more robust, see Long requests in the background.
- Understanding FlowModels error messages explains all error codes.