错误
Bitdeer AI API 的错误格式、状态码与重试建议。
非 2xx 响应以 OpenAI 错误结构返回 JSON:
application/json— 触发限流错误信息刻意保持通用,且可能变化。请根据 HTTP 状态码、type 和 code 这些稳定字段进行判断。
/v1/messages 改用 Anthropic 错误结构 —— 见 Anthropic 兼容错误。
HTTP 状态码
| HTTP | type | 可重试 | 含义 |
|---|---|---|---|
400 | invalid_request_error | 否 | 请求体不是合法 JSON、字段类型错误或超出范围、媒体 URL 不被允许,或 prompt 超出模型的上下文窗口 |
401 | authentication_error | 否 | API Key 缺失、格式错误、不存在或已过期 |
402 | insufficient_quota | 否 | 账户余额不足以支付本次请求,或存在未结清的费用 —— 请先充值 |
403 | permission_error | 否 | 你的账户无权使用所请求的模型,或账户不可用 |
404 | invalid_request_error | 否 | 没有该编码对应的可用模型,或该模型不支持此端点 |
405 | — | 否 | 该端点不接受此 HTTP 方法;响应体仅包含 message 和 type |
413 | invalid_request_error | 否 | 请求体超过 32 MiB 的大小限制 |
429 | rate_limit_error | 取决于 code | 超出了限流(默认 100 RPM)或 API Key 的用量额度 —— 见下方错误码 |
500 | server_error | 是 | 意外错误 |
501 | — | 否 | Bearer Token 形如 JWT 而非 API Key —— 见 鉴权 |
502 | server_error | 是 | 上游依赖暂时不可用 |
503 | server_error | 是 | 容量暂时耗尽或模型正在维护 —— 若有 Retry-After,请等待其指定的秒数,否则使用退避重试 |
504 | server_error | 是 | 模型未能及时响应 |
错误码
当存在具体情形时会设置 code,否则为 null。
code | 状态码 | 说明 |
|---|---|---|
invalid_api_key | 401 | API Key 缺失、格式错误、不存在或已过期 |
context_length_exceeded | 400 | prompt 超出模型的上下文窗口 |
model_not_found | 404 | 没有该编码对应的可用模型,或该模型不支持此端点 |
insufficient_balance | 402 | 账户余额不足以支付本次请求 |
rate_limit_exceeded | 429 | 你的账户超出了某项请求数或 token 数限流 —— 请退避后重试 |
insufficient_quota | 429 | 该 API Key 的用量额度已用尽;在额度提高之前重试不会成功 |
maintenance | 503 | 模型正在维护 —— 请稍后重试 |
限流
所有端点的默认限流为每分钟 100 次请求(100 RPM)。限流按账户计算,同时限制请求数和 token 数。超出时 API 返回 429,code 为 rate_limit_exceeded;请使用指数退避重试。
当某个 API Key 的用量额度用尽时,API 返回 429,code 为 insufficient_quota,并携带以下响应头:
| 响应头 | 说明 |
|---|---|
X-Quota-Used | 已计入该 Key 用量额度的请求数 |
X-Quota-Limit | 该 Key 的用量额度(按请求数计) |
请求 ID
每个响应(包括错误响应)都带有 X-Request-ID 响应头。联系技术支持时请提供该值。
错误结构
typestringrequired错误类别:
invalid_request_error、authentication_error、permission_error、rate_limit_error、insufficient_quota、server_error 或 api_error。messagestringrequired便于阅读的错误描述,不保证稳定。
codestring | nullrequired具体情形(如有)—— 见 错误码。
paramstring | nullrequired出错的请求字段名(如适用)。
Anthropic 兼容错误
/v1/messages 以 Anthropic 错误结构返回错误,便于 Anthropic SDK 解析:
request_id 与响应头 X-Request-ID 的值相同。
| HTTP | error.type |
|---|---|
400 | invalid_request_error |
401 | authentication_error |
402 | billing_error |
403 | permission_error |
404 | not_found_error |
413 | request_too_large |
429 | rate_limit_error |
500、502 | api_error |
503 | overloaded_error(Anthropic 官方使用 529) |
504 | timeout_error |
最后更新于