HTTP errors
| Status | Error code | Meaning | Recommended action |
|---|---|---|---|
| 400 | 400 / model_required | Invalid request parameters | Read message and correct the request body |
| 401 | invalid_api_key | The API key is invalid or revoked | Check the key on the API Keys page |
| 402 | payment_required | The wallet balance is insufficient | Top up the wallet |
| 403 | model_not_allowed | The API key model allowlist does not permit this model | Check the available models in the catalog |
| 403 | ip_not_allowed | The request IP is not in the API key allowlist | Update the IP rules on the API Keys page |
| 429 | 429 | An RPM or daily limit was exceeded, or upstream capacity is busy | Retry with exponential backoff |
| 500 | 500 | An internal ZeroFA error occurred | Contact us with the request_id |
| 502 / 503 | upstream_error / model_unavailable | The model is unavailable or an upstream request failed | Retry or choose another model |
Error response body
{
"error": {
"type": "rate_limit_exceeded",
"message": "RPM exceeded: 60/min",
"code": "429",
"param": null
}
}Every response includes an x-request-id header. Include it in support requests so we can locate the exact call context in the logs.
Rate limits
Each API key can have independent RPM and daily request limits. Configure them when creating or editing a key in API Keys. TPM is not currently enforced. Use exponential backoff after a 429 response.
Every response includes a trace ID. A rejection caused by a configured key quota also identifies the field that was exceeded:
X-Request-ID: 36356cd3-f7ad-4def-88d9-a7bd8ad2d167
X-Fornai-Quota-Field: rpmBilling model
ZeroFA uses a prepaid wallet with real-time usage billing. Charges are calculated from upstream tokens, images, seconds, and other usage at the model list price, then deducted from your Wallet in real time.
- Currency: configured currency, settled from actual usage in real time
- Failed requests are not charged (zero cost)
- If a stream disconnects early, generated tokens are still billed
- Prompt-cache hits are billed at the discounted cache_read rate
Prices
See live prices for each model in the Model Catalog; see the complete rules in Pricing and billing
Usage queries
- Aggregated statistics: Spend Analysis
- Individual calls: Usage Logs
- Wallet transactions: Wallet
- API: GET /api/me/usage/summary?group_by=day|model|api_key