跳到正文
HopBase 文档
登录控制台

报错速查

按错误信息快速排查协议、密钥、模型和环境问题。

按类别找到对应的现象。完整状态码表、重试规则与报障所需信息见错误码与重试。

网关按请求头 Accept-Language 返回简体中文、繁体中文、英文、日文或西班牙文文案，未指定时为英文；各表引用简体中文原文。

密钥、余额与权限

现象原因怎么做
401「缺少 API Key」
「API Key 无效」
「API Key 已过期」		没带密钥、复制不完整或多了空格，或密钥已删除、停用、过期回控制台「API 密钥」重新完整复制，必要时新建一把
402「余额不足」
「API Key 配额已用完」
「成员额度已用尽」
「部门额度已用尽」		账户余额、这把密钥的额度、企业成员或部门额度不足充值或调整额度后再发；402 不会自行恢复，不要循环重试
视频提交返回 402「Insufficient balance: available …」视频任务提交时的余额预留不足充值后再提交；不要循环重试
403「该账号已被禁用」
「该成员账号已被禁用」
「该成员无权使用此 API Key 所绑定的分组」
「API Key 未绑定任何分组，请联系管理员」
「当前分组未启用图片生成」		账户、成员或分组设置限制联络管理员；不要重试
404「该 API Key 所属分组已下线，不再处理请求…」密钥绑定的分组已下架在控制台用在售分组创建新密钥并替换

模型与路径

现象原因怎么做
404「当前分组不支持所请求的模型：X」
「该 API Key 所属分组未提供所请求的模型…」		模型 ID 不在这把密钥的任何分组里、拼写不完整，或客户端配置里残留已下架的 ID用该密钥调 GET /v1/models 复制完整 ID；列表里没有就在控制台给密钥加上该模型所在的分组；不要自动重试
404「当前平台不支持该 API 路径」Claude 密钥调了 OpenAI 协议接口Claude 改用 Anthropic 协议
同上Anthropic Base URL 多写 /v1（变成 /v1/v1/messages）Base URL 不带 /v1
同上调了平台不提供的接口，如 /v1/dashboard/billing/*、/v1/files、/v1/batches、/v1/embeddings查余额用 GET /v1/usage 或控制台
同上Codex 联网搜索调了 /v1/alpha/search这个 404 不影响对话
视频接口返回 404「当前平台不支持该 API 路径」视频路径写错按视频 API 用 POST /v1/video/generate 提交、GET /v1/video/tasks/{task_id} 查询

请求内容

现象原因怎么做
400「读取请求体失败」
「请求体必须为 JSON 对象，且字段类型须正确」
「缺少必填字段：model」
「messages 必须为非空数组」		请求体不完整或字段不合法检查 JSON 与 Content-Type
413「请求体超过大小限制（60 MB）」请求体超过 60 MB，多为 base64 图片、视频大文件先压缩，或在模型支持时改传 URL
400 输入超出上下文长度（原文因模型而异）对话历史、附件与 max_tokens 合计超过模型上下文裁剪历史或开新会话，调小 max_tokens
400「Invalid signature in thinking block」
「duplicate thinking.signature」		Claude 的 thinking 历史被改写、拼接或重复原样回传上一轮 assistant 的 thinking 块（含 signature），不要改写、合并或跨模型复用；修不好就从不含 thinking 的历史重新开始
400「No tool call found for function call output」
「No tool output found for function call」		工具结果与工具调用没有成对：tool_call_id / call_id 对不上，或少了一方每个工具调用都回传一条结果并原样带回 ID；删历史时成对删除
400「Unsupported parameter: …」模型不接受某个参数删掉该参数；Responses 接口限制输出长度用 max_output_tokens，不要用 max_tokens

图片与视频

现象原因怎么做
400 内容被安全策略拒绝（如「Your request was rejected by the safety system.」）提示词或参考素材触发模型的内容安全策略修改提示词或素材后再发，原样重试仍会被拒
400 图片参数错误（如「size … is not valid」）尺寸、档位或张数不在该模型支持范围按图片 API 里对应模型的取值修改
400「media_download_failed」参考图片或视频的 URL 无法公开访问换成不需要登录就能下载的 HTTP(S) URL
400「InputImageSensitiveContentDetected.PrivacyInformation」Seedance 2.0 对直接传入的真人参考图做隐私检测先用 POST /v1/sd/assets 上传为素材，再以 asset://素材ID 引用，详见视频 API
异步任务轮询返回 status: "failed"（如「the prompt was rejected by content moderation; rephrase it and submit again」）原因在 error.message，无 code，不扣费按提示修改后再提交；见错误码与重试
想知道某个异步任务实际扣了多少任务结束后查询响应里就有读根对象的 usage.cost_usd（从余额扣除的美元金额）、usage.cost（同一笔的人民币金额）与 usage.currency（未扣费的失败为 0）；任务列表里每个终态任务的 usage 也带这些字段，见视频 API

限流、超时与中断

现象原因怎么做
429「用户并发已达上限，请稍后重试」
「API Key 并发已达上限，请稍后重试」		同时在途的请求超过账户或密钥的并发上限在客户端排队限流，按响应头 Retry-After 稍后再发；上限见并发、超时与计费
429「…当前受到限流，请稍后重试」
502「…服务暂时不可用，请稍后重试」
503「当前没有可用的…，请稍后重试」
503「请求暂时无法完成，请稍后重试」
504「…请求超时，请稍后重试」
503「认证服务暂时不可用，请重试」		服务暂时不可用或响应超时按 Retry-After 或指数退避重试，也可换同系列模型；持续超过 10 分钟，带上响应头里的 X-Request-ID 联系我们
503「本次对话绑定的有状态会话已无法继续…」原会话已无法接续去掉 previous_response_id 开新对话
请求中途断开，记录为 499客户端在完成前主动断开：手动中断，或客户端读超时先到（openai-python 默认 600 秒，其他客户端各不相同）长输出改用流式，并调大客户端读超时
流式输出到一半收到错误事件（如「Response stream interrupted, please retry」）或连接断开已开始输出后出错，无法在同一条流里续传丢弃已收到的片段，整条请求重新发起

本机环境

现象原因怎么做
「node / npm 不是内部或外部命令」Node.js 没装好或没进 PATH到 nodejs.org 重装（Windows 保持默认勾选），装完关掉终端重新开启
PowerShell 提示「禁止执行脚本」Windows 脚本执行策略限制优先用控制台「一键接入」的命令；或以系统管理员执行 Set-ExecutionPolicy RemoteSigned

按表排查后仍未解决？请带上客户端名称、模型 ID、发生时间、HTTP 状态码、响应头里的 X-Request-ID 和已隐藏密钥的截图，联系我们。

下一步

本页目录

密钥、余额与权限模型与路径请求内容图片与视频限流、超时与中断本机环境下一步