HTTP 错误码
| 状态码 | 错误码 | 含义 | 建议 |
|---|---|---|---|
| 400 | 400 / model_required | 参数错误 | 查看 message 并修正请求体 |
| 401 | invalid_api_key | API key 无效或已吊销 | 在 API Keys 页面检查 |
| 402 | payment_required | 钱包余额不足 | 为钱包充值 |
| 403 | model_not_allowed | 当前 API key 的模型白名单不允许该 model | 在模型广场确认可用列表 |
| 403 | ip_not_allowed | 请求 IP 不在 API key 白名单中 | 在 API Keys 页面更新 IP 规则 |
| 429 | 429 | 超过 RPM 或日调用限制，或服务上游繁忙 | 使用指数退避后重试 |
| 500 | 500 | ZeroFA 内部错误 | 携带 request_id 联系我们 |
| 502 / 503 | upstream_error / model_unavailable | 模型暂不可用或 upstream 调用失败 | 重试或更换 model |
错误响应体
错误响应
{
"error": {
"type": "rate_limit_exceeded",
"message": "RPM exceeded: 60/min",
"code": "429",
"param": null
}
}每次调用都会返回 x-request-id 响应头。反馈问题时提供该 id，可帮助我们在调用日志中精确定位上下文。
限速
每个 API key 可独立配置 RPM 和日调用数限制，在 API Keys创建或编辑时设置。当前不执行 TPM 限制；遇到 429 时请使用指数退避。
所有响应都会返回追踪 ID；因自定义 key 限额被拒时还会标明触发字段：
追踪与限额响应头
X-Request-ID: 36356cd3-f7ad-4def-88d9-a7bd8ad2d167
X-Fornai-Quota-Field: rpm计费模型
采用预付钱包与实时按量扣费。系统根据上游返回的 tokens、images、seconds 等用量和模型刊例价，从 钱包管理 实时扣款。
- 计价单位：当前币种，按实际用量实时结算
- 失败请求不扣费（成本计 0）
- 流式请求中途断开时，按已生成 tokens 计费
- 缓存命中（prompt caching）按 cache_read 折扣价计费