主题
错误排查
常见报错速查表，遇到问题先对照这里检查。
401 Unauthorized（未授权）
| 可能原因 | 排查方法 |
|---|---|
| API Key 填错或多余空格 | 重新复制一次 Key，确认没有多余空格、引号 |
| Key 已被删除或禁用 | 登录控制台检查令牌状态 |
| Header 格式不对 | 确认是 Authorization: Bearer YOUR_API_KEY，不是直接填 Key |
404 Not Found
| 可能原因 | 排查方法 |
|---|---|
| Base URL 路径错误 | 按协议核对：OpenAI 填 https://api.aruhub.com/v1，Claude 填 https://api.aruhub.com |
| 模型名不存在 | 前往 模型广场 核对支持的模型名称 |
重复 /v1（如 /v1/v1/chat/completions）
很多 SDK 会自动在 Base URL 后面拼接 /v1，如果你填的 Base URL 已经带了 /v1，会导致路径重复。
解决方法：检查所使用的客户端 / SDK 文档，确认它是否会自动追加 /v1。如果会，Base URL 只需填 https://api.aruhub.com；如果不会，则按本文档其他页面填写 https://api.aruhub.com/v1。
长任务超时
| 可能原因 | 排查方法 |
|---|---|
| 客户端默认超时时间过短 | 在客户端设置中调大超时时间 |
| 网络环境不稳定 | 更换网络环境或重试 |
| 模型生成内容过长 | 适当拆分任务，减少单次请求的输出长度 |
400 Bad Request
错误表现
请求返回 HTTP 400，通常表示请求正文或参数不符合当前接口要求。请求一般会在模型开始生成前被拒绝；错误正文会因模型和服务方而异。
常见原因
- JSON 格式错误，例如缺少逗号、引号或括号不匹配。
model、messages、input、stream等参数格式错误。- 缺少接口要求的必填字段。
- 参数类型错误，例如把布尔值写成字符串。
- 使用了当前模型或接口不支持的参数。
- 把 Chat Completions 与 Responses API 的参数混在同一个请求中。
排查步骤
- 用 JSON 校验工具确认请求正文可以正常解析。
- 核对请求地址，确认正在调用
/v1/chat/completions、/v1/responses或其他目标接口。 - 对照该接口文档逐项检查必填字段、字段类型和嵌套结构。
- 临时移除可选参数，只保留最小请求，再逐项加回参数定位问题。
- 查看返回正文，但不要假设所有模型都会返回相同格式的错误 JSON。
请求头可先按以下通用形式检查：
http
POST https://api.aruhub.com/v1/chat/completions
Authorization: Bearer sk-xxxxxxxx
Content-Type: application/json解决方法
修正 JSON、补齐必填字段，并只使用目标接口和模型支持的参数。不要把 Chat Completions 的 messages 与 Responses API 的 input 直接混用。
请求重试原则
请求正文未修正前，不建议对完全相同的 400 请求反复重试；重复提交通常不会自行恢复。
联系客服时需要提供的信息
- 完整请求时间（含时区）和请求接口。
- 模型 ID、HTTP 状态码和完整错误正文。
- 已脱敏的请求参数结构，隐藏对话隐私和 API Key。
- 客户端或 SDK 名称及版本。
403 Forbidden
错误表现
请求返回 HTTP 403。系统通常已经识别了你的身份，但当前身份没有访问目标模型、分组或管理接口的权限。
常见原因
- 当前 API Key 没有该模型的使用权限。
- 当前账户分组不支持该模型。
- Token 或账户已被禁用。
- 模型仅允许特定分组使用。
- 访问了需要管理员权限的接口。
排查步骤
- 登录控制台确认账户和 API Key 状态正常。
- 查看价格页或模型列表，确认当前分组可见并支持该模型。
- 核对是否误用了管理接口或管理员专用路径。
- 用同一个 Key 请求允许访问的模型，判断问题是否只影响特定模型。
- 保留错误正文中的请求 ID 或追踪信息（如有）。
解决方法
改用当前分组支持的模型或有权限的接口；如果 Key 或账户被禁用，请通过控制台联系支持核实。不要通过连续重试绕过权限限制。
401 通常表示身份凭证无效或未正确提供；403 通常表示身份已经被识别，但没有相应访问权限。
联系客服时需要提供的信息
- 完整请求时间（含时区）、模型 ID 和接口路径。
- HTTP 状态码、完整错误正文和请求 ID（如有）。
- 当前账户分组与 API Key 的末尾几位，切勿提供完整 API Key。
- 能否正常调用其他模型或接口。
413 Payload Too Large
错误表现
请求返回 HTTP 413，或客户端提示请求体太大。请求通常在完整内容进入模型处理前被拒绝。
常见原因
- 请求上下文过长。
- 上传的图片、文件或 Base64 内容过大。
- 请求体超过服务链路允许的大小。
- 客户端一次提交了过多历史消息。
排查步骤
- 统计请求正文大小，并检查是否包含很长的 Base64 字符串。
- 减少历史消息后再次测试，确认是否由上下文累积引起。
- 检查图片分辨率、文件体积和单次上传数量。
- 确认客户端没有重复附加同一份历史记录或文件。
- 区分输入体积与输出长度：
max_tokens通常控制输出长度，不等于请求体大小。
解决方法
- 删除与当前任务无关的历史消息。
- 压缩图片，选择合理的分辨率和格式。
- 减少单次上传的文件数量。
- 把长文档或复杂任务拆成多次请求。
- 不要只修改
max_tokens；应直接减少输入内容或附件体积。
联系客服时需要提供的信息
- 完整请求时间（含时区）、模型 ID 和接口类型。
- 请求正文的大致体积、消息数量和附件数量。
- 附件类型及压缩后的大小，不要发送包含隐私的原始文件。
- HTTP 状态码和完整错误正文。
429 Too Many Requests
错误表现
请求返回 HTTP 429，可能表现为频率限制、并发限制、额度不足或服务繁忙。不同模型服务返回的错误正文可能不同，不能只凭状态码断定唯一原因。
常见原因
- 短时间内请求频率过高。
- 同时进行的请求数量超过限制。
- 模型服务方（技术上也称上游服务）暂时限流。
- 账户余额或额度不足。
- 同一个 Key 被多个客户端同时使用。
- 可用服务节点暂时繁忙。
排查步骤
- 查看错误正文，确认是否提到频率、并发、额度或余额。
- 检查控制台余额和对应时间的用量记录。
- 暂停其他客户端，确认同一 Key 是否被并行使用。
- 降低并发后发送单个小请求，观察是否恢复。
- 记录模型、时间、请求 ID 和重试等待提示（如有）。
解决方法
- 降低请求频率和并发数。
- 按错误提示等待后重试。
- 使用带随机抖动的指数退避，例如逐步延长等待时间。
- 检查余额、额度和用量记录。
- 避免毫无间隔地循环重试，也不要让多个客户端共享一个 Key 进行高并发调用。
联系客服时需要提供的信息
- 完整请求时间（含时区）、模型 ID 和接口路径。
- 当时的并发数、请求频率和重试策略。
- HTTP 状态码、完整错误正文和请求 ID（如有）。
- 对应时段的余额与用量记录截图，隐藏完整 API Key。
502 Bad Gateway
错误表现
请求返回 HTTP 502，表示服务链路中的某个环节没有取得有效响应。仅凭该状态码，不能判断是 AruHub 平台自身故障还是模型服务暂时异常。
常见原因
- 模型服务暂时不可访问。
- 模型服务连接异常。
- DNS、TLS 或代理链路出现临时异常。
- 模型服务返回了无效响应。
- 临时网络波动导致连接失败。
排查步骤
- 判断是偶发一次，还是同一模型持续出现。
- 用较小的请求测试同一模型，并避免立即并发重试。
- 检查其他模型是否可用，以缩小问题范围。
- 记录完整请求时间、模型 ID、请求 ID 和错误正文。
- 如果请求曾开始输出，先检查用量记录再决定是否重试。
解决方法
偶发的 502 可以稍等后重试，并使用指数退避。若持续发生，可暂时改用价格页或 /v1/models 中当前可用的其他模型；不要假设所有错误都会自动切换服务节点。
联系客服时需要提供的信息
- 完整请求时间（含时区）和模型 ID。
- 接口路径、HTTP 状态码及完整错误正文。
- 请求 ID 或追踪信息（如有）。
- 是否开始输出、是否重试以及其他模型是否正常。
503 Service Unavailable
错误表现
请求返回 HTTP 503，通常表示目标模型当前没有可用的服务能力，或模型服务正处于维护、繁忙状态。
常见原因
- 当前没有可用渠道。
- 对应模型暂时没有可用账号或服务节点。
- 模型服务维护或容量不足。
- 模型临时下线。
- 可用渠道的健康检查未通过。
排查步骤
- 在价格页或
/v1/models中确认目标模型是否仍对当前账户可见。 - 查看错误正文是否提示无可用渠道、维护或服务繁忙。
- 测试当前账户可用的其他模型，确认影响范围。
- 记录错误发生时间、模型 ID 和请求 ID。
- 如果请求已经开始输出，先检查用量记录，不要直接重复提交大任务。
解决方法
等待一段时间后重试，或选择当前账户可用的其他模型。系统是否会切换渠道，取决于请求是否已经开始输出、错误类型和实际渠道配置，因此不能承诺每个 503 都会自动切换。
联系客服时需要提供的信息
- 完整请求时间（含时区）、模型 ID 和接口类型。
- HTTP 状态码、完整错误正文和请求 ID（如有）。
- 该模型是否显示在价格页或
/v1/models中。 - 其他模型是否可用、请求是否曾开始输出。
504 Gateway Timeout
错误表现
请求返回 HTTP 504，或在长时间等待首个 Token 后超时。它表示某一层等待超过时限，但不一定代表模型服务最终没有执行任务。
常见原因
- 模型任务执行时间过长。
- 首 Token 等待时间过长。
- 客户端、代理或模型服务响应超时。
- 长文本、高推理、图片或视频任务耗时较长。
排查步骤
- 记录请求提交时间、超时时间和错误出现时间。
- 先检查控制台用量记录，确认该请求是否已经产生消费。
- 检查客户端超时配置，并区分连接超时、首 Token 超时和总时长超时。
- 减小输入或拆分任务后再测试，不要直接重复提交同一个大任务。
- 查看错误正文和请求 ID（如有），判断超时发生在哪类任务。
解决方法
适当提高客户端超时时间，优先使用流式响应，并拆分长文本、高推理、图片或视频任务。发生 504 后不要立即连续重复提交相同的大任务，应先核对用量记录，避免重复调用和重复计费风险。
重要
504 不等于请求一定未执行。确认状态和消费记录之前，不建议连续重试同一大任务。
联系客服时需要提供的信息
- 完整请求时间（含时区）、模型 ID、接口和任务类型。
- 客户端设置的超时时间、HTTP 状态码和完整错误正文。
- 请求 ID（如有）以及是否收到任何输出。
- 对应时段的用量或消费记录，隐藏完整 API Key。
流式响应中断
错误表现
- 输出到一半停止。
- 长时间等待后连接断开。
- 出现
connection reset、context canceled、client_gone或broken pipe。 - 浏览器或客户端显示网络错误。
常见原因
- 用户主动点击停止或取消任务。
- 客户端、浏览器标签页或应用被关闭。
- 本地网络断开或切换。
- 客户端等待时间过短而主动超时。
- 代理或服务链路中断。
- 模型服务输出异常。
排查步骤
- 确认是否主动停止、关闭客户端或切换网络。
- 查看中断前是否已经收到部分输出。
- 检查客户端超时时间、自动重试设置和网络日志。
- 查看控制台同一时间的状态、用量和消费记录。
- 记录模型 ID、请求 ID、中断时间和客户端显示的原始错误。
解决方法
先修复网络或客户端超时问题，再根据已产生的输出和计费记录决定是否重试。客户端取消不一定代表模型服务会立即停止；中断请求也可能无法获得完整 usage，因此不要把所有流式中断都判断为模型故障。
是否重试应先检查任务是否已经产生输出或消费记录。对于可拆分任务，可从已确认完成的位置继续，避免重复生成全部内容。
联系客服时需要提供的信息
- 完整请求时间（含时区）、模型 ID 和接口路径。
- 中断前收到的输出范围，以及是否主动停止。
- 客户端名称、版本、超时设置和原始网络错误。
- 请求 ID、用量与消费记录；不要提供完整 API Key 或敏感对话内容。
模型不可用
错误表现
请求提示模型不存在、无权限、无可用渠道、接口不支持，或价格页可以看到名称但实际调用失败。
常见原因
- 模型名称拼写错误。
- 使用了展示名称，而不是实际模型 ID。
/v1/models返回列表中没有该模型。- 当前账户分组不支持该模型。
- 当前没有启用渠道或可用服务节点。
- 模型暂时维护或下线。
- 调用了该模型不支持的接口类型。
排查步骤
- 先查看价格页或请求
/v1/models，复制当前账户可用的实际模型 ID。 - 检查大小写、空格、前后缀和版本日期是否完全一致。
- 核对账户分组与模型权限。
- 确认模型能力与接口类型匹配。
- 查看完整错误正文，区分模型不存在、权限不足和暂时无可用渠道。
解决方法
改用价格页或 /v1/models 返回的实际模型 ID，并选择该模型明确支持的接口和能力。文本模型存在，不代表它支持图片生成接口；支持 /v1/chat/completions 不代表一定支持 /v1/responses；支持某个模型名称也不代表所有工具调用能力都可用。
联系客服时需要提供的信息
- 完整请求时间（含时区）和实际提交的模型 ID。
- 接口路径、HTTP 状态码及完整错误正文。
- 当前账户分组，以及
/v1/models中是否存在该模型。 - 使用的能力类型，例如文本、图片、工具调用或文件输入。
用量显示 N/A 或请求成功但 Token 为 0
错误表现
请求可能已经返回内容或显示成功，但用量字段显示 N/A，或者输入、输出 Token 显示为 0。
常见原因
- 流式请求提前中断。
- 用户主动取消任务。
- 服务方未返回完整用量信息。
- 客户端在最终统计事件到达前断开。
- 请求可能已经被模型服务处理，但平台没有拿到完整统计。
- 某些特殊接口使用不同的用量统计方式。
排查步骤
- 检查调用时间、模型 ID、请求状态和返回正文。
- 查看同一时段的用量与消费记录，而不是只看 Token 字段。
- 确认请求是否为流式调用、是否提前中断或被主动取消。
- 查看客户端是否接收到最终统计事件或完整
usage。 - 保留请求 ID、时间和已脱敏日志，用于核对服务方返回情况。
解决方法
N/A 不等于一定没有产生模型服务消耗，Token 为 0 也不应直接理解为免费调用。先结合状态、返回正文和消费记录判断；如果客户端经常在最终事件前断开，应调整超时设置并确保完整读取流式响应。
联系客服时需要提供的信息
- 完整请求时间（含时区）、模型 ID、接口和是否使用流式响应。
- 请求状态、完整返回正文、请求 ID 和已脱敏客户端日志。
- 对应时段的用量与消费记录截图。
- 不要提供完整 API Key；争议核对需要准确时间和日志，而不是密钥本身。
仍未解决？
如果以上步骤都无法解决问题，请保留报错信息（包括状态码、返回内容），通过控制台联系支持。