开发者
错误、限额与计费
错误码含义、排查顺序、速率与消费限额，以及余额怎么扣。
错误响应的形状
所有错误都是 OpenAI 格式：
{
"error": {
"message": "API key is missing the \"images\" scope (it has: chat, responses, embeddings). Grant it on the key, or create a new key with this scope.",
"type": "permission_error",
"code": "developer_api_scope_denied",
"param": null,
"detail": {
"requiredScope": "images",
"grantedScopes": ["chat", "responses", "embeddings"]
}
}
}
**先读
message 和 detail。**4xx 错误的这两个字段会直接写明下一步该做什么——缺哪个权限、
该轮询哪个任务、哪个参数不对。不要只看 code 就去猜。常见错误码
code | HTTP | 含义与处理 |
|---|---|---|
invalid_api_key | 401 | Key 不对或已被吊销。检查有没有复制完整 |
api_key_disabled | 401 | Key 被停用了 |
api_key_expired | 401 | Key 过期了 |
api_key_ip_not_allowed | 403 | 你的出口 IP 不在这把 Key 的 IP 白名单里 |
developer_api_scope_denied | 403 | Key 缺少这个端点需要的权限，见下文 |
model_not_allowed | 403 | 这把 Key 设了模型白名单，不含这个模型 |
model_not_found | 404 | 这个模型不存在，或你的账户无权使用。先 GET /v1/models |
insufficient_credits | 403 | 余额不足。detail 里带着本次所需与当前余额 |
model_pricing_required | 503 | 这个模型还没配价，联系管理员 |
rate_limit_exceeded | 429 | 触发速率限制，退避后重试 |
daily_spend_limit_exceeded | 429 | 这把 Key 的当日消费上限到了 |
monthly_spend_limit_exceeded | 429 | 这把 Key 的当月消费上限到了 |
image_generation_timeout | 504 | 生图超时，但任务还在跑，用 detail.taskId 去取 |
upstream_unavailable | 502 / 503 | 上游模型服务出问题，可以重试 |
bad_request | 400 | 参数不对，message 里会写明是哪个字段 |
权限范围（scope）
每把 Key 带一组 scope，决定它能用哪些端点：
| scope | 开放的端点 |
|---|---|
chat | /v1/chat/completions |
responses | /v1/responses |
embeddings | /v1/embeddings |
images | /v1/images/generations、/v1/tasks（图片） |
videos | /v1/videos、/v1/tasks（视频） |
新建的 Key 默认带上以上全部。audio 这个 scope 暂时没有对应的端点。
GET /v1/models 返回的模型也受 scope 过滤——一把只有 chat 的 Key 在列表里看不到生图模型。
所以「模型列表里没有我要的模型」往往是 scope 问题，不是模型不存在。限额
每把 Key 可以单独设：
- RPM — 每分钟请求数
- 每日请求数
- 每日消费上限 / 每月消费上限
- 模型白名单 — 只允许用列出的模型
- IP 白名单 — 只允许从列出的 IP 调用
此外模型本身也可能有每日配额（请求数、图片张数等），触发时同样返回 429rate_limit_exceeded——message 会区分是哪一种。
计费
调用按账户余额扣费，与你在 BotHub 客户端里用内置 AI 是同一个余额。
- 对话 / 向量：按 token 计费，区分输入、输出和缓存命中
- 生图：按张计费
- 视频：按模型配置的计量单位（时长等）计费
请求进来时会先冻结一笔押金，结束后按真实用量结算，多退少补——超出押金的部分照常入账。 所以偶尔会看到余额先掉一块、随后回补一部分，这是正常的。
余额不足时返回 insufficient_credits，detail 里带着本次所需金额和当前余额（单位：分）：
{
"error": {
"code": "insufficient_credits",
"detail": { "requiredFen": 320, "balanceFen": 95 }
}
}
查用量最方便的地方就是创建密钥的那个页面——App 里的「外部调用」会按每把密钥列出最近 7 天 的调用次数、token 数和花费。
排查顺序
调不通时按这个顺序查，通常前两步就能定位：
GET /v1/models能不能通？- 401 → Key 的问题（复制不全、被吊销、过期）
- 能通但列表里没有你要的模型 → scope 或账户权限问题
- 模型在列表里，但请求报错？ 看
endpoints字段，确认你发对了端点—— 生图模型发到/v1/chat/completions是不会工作的 - 403？ 读
message，它会写明缺的是哪个 scope，还是 IP 白名单、余额的问题 - 429？ 可能是 RPM、日请求数、消费上限或模型配额，
message会说是哪一种；退避后重试 - 504 生图超时？ 任务没有失败，用
detail.taskId去GET /v1/tasks/{id}取结果， 并把客户端超时调长 - 502 / 503？ 上游模型服务的问题，退避后重试