HopBase 文档错误码与重试
HopBase 的错误响应结构、各状态码的含义与能否重试、流式请求出错的表现，以及报障时需要提供的信息。
按现象快速定位用报错速查，本页是完整口径。并发上限、超时与计费规则见并发、超时与计费。
错误响应结构
OpenAI 协议（/v1/chat/completions、/v1/responses、/v1/images/*、/v1/video/*）：
{ "error": { "message": "…", "type": "invalid_request_error", "code": "insufficient_quota" } }Anthropic 协议（/v1/messages）：
{ "type": "error", "error": { "type": "invalid_request_error", "message": "…" } }文案语言按请求头 Accept-Language 返回，未指定时为英文。程序里请按 HTTP 状态码和 code 判断，不要匹配文案。
状态码
| 状态码 | 典型原因 | 能否重试 | 怎么做 |
|---|---|---|---|
| 401 | 没带密钥、密钥不完整、已停用或过期 | 否 | 回控制台「API 密钥」重新复制或新建 |
| 402 | 帐户余额用完；这把密钥的额度用完；视频提交时余额不足以覆盖在途预留 | 充值后可 | 充值或调整密钥额度；不要循环重试 |
| 403 | 分组限制了客户端，或该能力未开通 | 否 | 换成该分组适用的客户端或分组 |
| 404 | 模型不在这把密钥的分组里、路径不属于该分组、分组已下线 | 否 | 用该密钥调 GET /v1/models 核对 ID；路径见Base URL 与协议 |
| 413 | 请求体超过 60 MB | 否 | 压缩素材，或在模型支持时改传 URL |
| 429 | 帐户或密钥并发已达上限；或该模型当前受限流 | 是 | 按 Retry-After 稍后重试并降低并发 |
| 499 | 客户端在完成前断开（手动中断或读超时先到） | 是 | 长输出改用流式，并调大客户端读超时 |
| 502 / 503 | 该模型暂时不可用，系统已自动换号重试仍未成功 | 是 | 退避重试，或换同系列的其他模型 |
| 504 | 上游处理超时 | 是 | 退避重试；长任务改用流式或异步接口 |
404 里有一类其实是「暂时不可用」
收到 Model "X" is not supported by any configured account in this group 时，先用这把密钥调 GET /v1/models：列表里有这个模型，说明它只是暂时不可用，按 502 / 503 处理；列表里没有，才是分组不含该模型。
重试规则
- 不要原样重试：400、402、403、404、413、422。这些要先改请求、配置或余额。
- 退避后重试：429、502、503、504，以及流式输出中断。建议间隔 2 秒、5 秒、15 秒，最多 3 次。
- 429 会带重试提示头：
Retry-After（秒）与Retry-After-Ms（毫秒），有就按它等待。 - 异步任务提交成功后不要重复提交：视频和异步生图提交成功即已创建任务，重复提交会产生多个任务并各自计费，改为轮询任务状态。
流式请求出错
流式请求一旦开始输出，HTTP 状态码就已经是 200，之后的错误通过事件下发，不会再改状态码：
- OpenAI 协议：
event: error，Responses 协议为response.failed。 - Anthropic 协议：
event: error。
客户端要在读流的循环里处理错误事件。已收到的片段无法续传，需要整条请求重新发起。
报障时请提供
- 响应头
x-request-id（每条响应都有，是定位该请求的唯一标识） - 出现时间（带时区）与模型 ID
- 完整的报错原文与 HTTP 状态码
带上这些信息联系我们，可以直接定位到那一条请求。