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": "…" }
}Anthropic 结构没有 code。密钥校验阶段的错误（401、额度 402、帐户 403）在 /v1/messages 也是 OpenAI 结构。文案语言按请求头 Accept-Language 返回，未指定时为英文。程序里请按 HTTP 状态码和 code 判断，不要匹配文案。
状态码
| 状态码 | 典型原因 | 能否重试 | 怎么做 |
|---|---|---|---|
| 401 | 没带密钥、密钥不完整、已停用或过期 | 否 | 回控制台「API 密钥」重新复制或新建 |
| 402 | 余额、密钥、成员或部门额度用完；视频提交时余额不足以覆盖在途预留 | 充值后可 | 先用 GET /v1/usage 查这把密钥还能花多少，再充值或调整额度；不要循环重试 |
| 403 | 帐户或成员被停用、无权使用或未绑定分组，或能力未开通 | 否 | 联系管理员，或换用支持该调用的分组密钥 |
| 404 | 模型不在这把密钥的分组里、路径不属于该分组、分组已下线 | 否 | 用该密钥调 GET /v1/models 核对 ID；路径见Base URL 与协议；已下架的 ID 及替代型号见模型更新日志 |
| 413 | 请求体超过 60 MB | 否 | 压缩素材，或在模型支持时改传 URL |
| 429 | 帐户或密钥并发已达上限；或服务当前繁忙 | 是 | 按 Retry-After 稍后重试并降低并发 |
| 499 | 只见于控制台使用记录：客户端先断开，收不到它 | — | 长输出改用流式，并调大客户端读超时 |
| 502 / 503 | 服务暂时不可用，系统自动重试仍未成功 | 是 | 退避重试，或换同系列的其他模型 |
| 504 | 处理超时 | 是 | 退避重试；长任务改用流式或异步接口 |
错误码清单
# OpenAI 结构里的 code。模型自身返回的 400 可能带该模型自己的 code。
状态 code 含义 能否重试
401 missing_api_key 没带密钥 否
invalid_api_key 密钥无效或已删除 否
api_key_expired 密钥已过期 否
402 insufficient_quota 余额 / 密钥 / 成员 / 部门额度用完 充值后
insufficient_balance 视频：余额不足以覆盖在途预留 + 本条预估 任务结束或充值后
403 account_disabled 帐户已停用 否
member_disabled 成员帐号已停用 否
member_group_forbidden 成员无权使用这把密钥的分组 否
api_key_misconfigured 密钥未绑定分组 否
image_generation_disabled 分组未开通生图 否
middleware_denied 被网关策略拒绝 否
404 model_not_found 分组不支持该模型 否
model_not_served 分组未提供该模型 否
group_offline 分组已下线 否
route_not_found 该密钥不支持此路径 否
400 invalid_request 请求体无法读取或不是 JSON 对象、缺 model、messages 为空 否
413 request_too_large 请求体超过 60 MB 否
429 user_concurrency_limit 帐户并发上限（Retry-After: 1） 是
apikey_concurrency_limit 密钥并发上限（Retry-After: 1） 是
all_routes_rate_limited 服务繁忙 是
upstream_rate_limit 服务繁忙 是
502 upstream_error 服务暂时不可用 是
503 no_available_route 服务繁忙 是
no_available_account 服务繁忙（会话续接例外见下） 是*
all_routes_failed 服务暂时不可用 是
plugin_unavailable 服务暂时不可用 是
service_unavailable 认证服务暂时不可用 是
504 upstream_timeout 超时 是重试规则
- 不要原样重试：400、402、403、404、413、422。这些要先改请求、配置或余额。404 是确定结果：暂时不可用只返回 429 / 5xx，不会返回 404。
- 退避后重试：429、502、503、504，以及流式输出中断。建议间隔 2 秒、5 秒、15 秒，最多 3 次。例外：提示有状态会话「can no longer be resumed」的 503，要去掉
previous_response_id开新对话。 - 429 会带重试提示头：
Retry-After（秒）与Retry-After-Ms（毫秒），有就按它等待。 - 异步任务提交成功后不要重复提交：每次重提都是另一个各自计费的任务，请改为轮询。
流式请求出错
流式请求一旦开始输出，HTTP 状态码就已经是 200，之后的错误通过事件下发，不会再改状态码：
Chat Completions data: {"error": {…}} （不带 event: 行）
Responses event: response.failed （response.error.code：rate_limit_exceeded / server_error / invalid_prompt）
Anthropic event: error客户端要在读流的循环里处理错误事件。已收到的片段无法续传，需要整条请求重新发起。
异步任务失败
提交被拒直接返回普通 4xx，不建任务。受理后失败时轮询仍返回 200，status: "failed"，原因在 error.message（生图任务为 error 字符串），没有 code（可灵与 Midjourney 任务例外，会返回稳定的 error.code，如 input_sensitive、invalid_request、generation_failed），不计费。审核类、参数类失败不要原样重提。控制台「使用记录」显示分类与建议：
审核 input_sensitive、safety_rejected … 改提示词或素材
参数 prompt_required、upstream_invalid_request、reference_* … 改参数
超时 各系列时限见「并发、超时与计费」 重新提交
中断 task_interrupted 重新提交报障时请提供
- 响应头
x-request-id（每条响应都有，是定位该请求的唯一标识） - 出现时间（带时区）与模型 ID
- 完整的报错原文与 HTTP 状态码
服务端故障在控制台不显示原文，排查以 x-request-id 为准。带上这些信息联系我们，可以直接定位到那一条请求。