Response Headers
All API responses include the following headers:
| Header | Description |
|---|---|
| X-Request-Id | Unique request identifier for debugging |
| X-RateLimit-Limit | Maximum requests per minute (60) |
| X-RateLimit-Remaining | Remaining requests in the current window |
| X-RateLimit-Reset | Unix timestamp (seconds) when the rate limit resets |
| X-Cache | HIT or MISS (only present when cache: true) |
| X-Model-Id | The model that actually served the request (only present when a fallback model was used) |
Rate limit headers are included for API key requests only, not browser session requests.
Rate Limits & Billing
- 60 requests per minute per API key
- Credits are deducted from your organization's balance (not per-user)
- When rate limited, you'll receive a
429response with aRetry-Afterheader (value in seconds) - Max 10 active API keys per user
- Pricing varies by model. Use the Models endpoint to see per-model costs.
Error Codes
| Code | Meaning |
|---|---|
| 400 | Invalid request (missing model, empty messages, invalid parameters, context overflow) |
| 401 | Invalid or expired API key |
| 402 | Insufficient credits |
| 403 | Model requires a paid plan / no organization |
| 408 | Request timed out (all models exceeded the timeout) |
| 429 | Rate limit exceeded, OR the organization has hit its 6-hour usage window. Window errors carry error code WINDOW_EXHAUSTED and include resetAt (ISO-8601). Buy top-up credits to continue immediately, or wait for the window to roll over. |
| 500 | Internal server error |
| 502 | All models failed (primary + all fallbacks exhausted) |
Credit Reservation
To prevent concurrent requests from overselling the same balance, every billed endpoint reserves credits up-front before starting work. The reservation is settled on completion:
- Success — the reservation is converted into a charge (exact token cost for chat, fixed tier cost for image/video).
- Failure — the reservation is released and the balance is untouched (provider error, invalid input, download failure, webhook delivery failure, etc.).
- Queued image/video jobs (
202 Accepted) — the reservation stays held until the fal webhook fires; a successful delivery charges, a failed delivery releases.
The practical impact for callers: a 402 or 429 returned before work starts means zero credits were used; balance changes are visible only after a successful response or webhook.
OpenAI-Compatible Error Types
The /v1/chat/completions endpoint wraps errors in an OpenAI-shaped envelope:
{ "error": { "message": "…", "type": "rate_limit_exceeded" } }| Status | type |
|---|---|
| 400 | invalid_request_error |
| 401 | invalid_request_error |
| 402 | insufficient_quota |
| 429 | rate_limit_exceeded |
| 5xx | api_error |