错误码

这一页按常见 HTTP 状态码解释请求失败原因。实际错误字段以当前后端返回为准。

排查时先看两处：

• HTTP 状态码，例如 401、429。
• 响应 JSON 里的 error.code 或 error.message。

WARNING

联系支持时不要提供完整 API Key。可以提供 Key 名称、Key 前后几位、请求时间、Base URL、模型名、状态码和错误信息。

401 Unauthorized

通常表示鉴权失败。

可能原因：

• API Key 错误。
• 请求头格式错误。
• Key 已删除或失效。

你应该做：

1. 确认请求头是 Authorization: Bearer <你的 API Key>。
2. 重新从 Arqel 控制台复制 Key。
3. 如果使用环境变量，重新设置并打开新终端。
4. 确认没有把引号、空格或换行复制进 Key。

通常不需要支持介入，除非你确认 Key 正确但持续返回 401。

403 Forbidden

通常表示没有权限调用当前资源或模型。

可能原因：

• 当前 Key 没有权限调用该模型。
• 当前账户、组织或套餐不允许访问该资源。
• 目标模型暂未对当前账户开放。

你应该做：

1. 回到控制台确认模型在可用列表中。
2. 确认使用的是这个账户创建的 Key。
3. 换一个控制台中可用的具体模型名测试。

如果权限看起来正确但仍失败，需要联系支持。提供请求时间、Key 名称、模型名和错误信息，不要提供完整 Key。

404 Not Found

通常表示路径不存在、Base URL 错误，或模型名无法识别。

可能原因：

• Base URL 写错。
• 请求路径写错。
• SDK 自动拼接路径后变成了错误地址。
• 模型名不是控制台中的具体模型名。

你应该做：

1. 重新复制 Arqel 控制台中的 Base URL。
2. 检查是否重复写了 /v1 或漏掉 /v1。
3. 如果是 Agent，确认 Base URL 填在当前工具真正读取的 Provider / Endpoint 字段里。
4. 如果是 API / SDK，检查请求路径。
5. 重新从控制台复制模型名。

通常不需要支持介入，除非控制台示例也失败。

429 Too Many Requests

通常表示请求过于频繁、达到限制，或上游限流。

可能原因：

• 短时间请求太多。
• Agent 进入循环调用。
• 账户余额或额度不足。
• 上游模型服务限流。

你应该做：

1. 暂停自动化 Agent，先确认没有进入循环调用。
2. 等待一段时间后重试；如果响应里有 Retry-After，以它为准。
3. 检查 Arqel 控制台用量、余额和限制。
4. 降低并发和请求频率，重试要设置最大次数，不要无限重试。

如果持续出现 429，需要联系支持或查看当前套餐/限额。

500 / 502 / 503

通常表示服务端或上游模型临时异常。

建议稍后重试，并查看控制台状态或公告。

可能原因：

• Arqel 服务临时异常。
• 上游模型服务异常。
• 网络链路或网关异常。
• 请求触发了未处理的后端错误。

你应该做：

1. 稍后重试一次；自动重试请使用有限次数的指数退避。
2. 换一个控制台中可用的具体模型名测试。
3. 如果是 Agent 工具，先确认控制台是否出现该 Agent 请求记录，以及是否只有某个 Agent 失败。
4. 只有在深度排障时，才需要用 API 调用示例或 SDK 单独检查请求结构。
5. 如果持续失败，联系支持。

联系支持时提供：

• 请求时间和时区。
• Base URL。
• 模型名。
• HTTP 状态码。
• 错误信息。
• 使用的工具或 SDK。
• 工具或 SDK 版本（如果知道）。
• 请求 ID / trace ID（如果响应或控制台提供）。

不要提供完整 API Key、完整私有提示词、客户数据或未打码截图。

重试原则

401 和 403 通常不是临时错误，不要自动重试。429、500、502、503 可以短暂重试，但要限制次数、降低并发，并优先排查是否有 Agent 循环调用。

快速对照表

状态码	常见原因	先做什么	是否通常需要支持
401	Key 或鉴权头错误	重新复制 Key，检查 Bearer	通常不需要
403	没有权限	检查模型权限和账户权限	可能需要
404	路径、Base URL 或模型名错误	重新复制 Base URL 和模型名	通常不需要
429	限流、额度、请求过多	降低频率，检查用量	可能需要
500	服务端错误	稍后重试，保留错误信息	如果持续出现则需要
502	网关或上游异常	稍后重试或换模型	如果持续出现则需要
503	服务暂不可用	稍后重试，查看公告	如果持续出现则需要