调用 API 失败时，先看 HTTP 状态码，再看返回的错误信息。状态码可以帮助你快速判断问题出在请求配置，还是服务端暂时异常。

快速判断： 4xx 通常是请求、密钥或账号配置问题，请先按本文自查；5xx 通常是网关、上游模型或服务器暂时异常，可以稍后重试，持续出现时再联系我们。

4xx：客户端或账号配置问题

400 Bad Request

请求内容不符合接口要求。常见原因包括 JSON 格式错误、字段名拼写错误、参数类型不正确，或使用了接口不支持的参数。

处理方法： 检查请求体格式和字段名称，并对照对应接口文档重新提交。

401 Unauthorized

身份验证失败。常见原因包括没有携带 API Key、Key 填写错误或已失效，以及 Authorization 请求头缺少 Bearer 前缀。

处理方法： 重新复制 API Key，确认请求头格式为 Authorization: Bearer 你的API Key，并检查 Key 前后是否有多余空格。

403 Forbidden

服务器识别了请求，但当前 Key 没有访问权限。常见原因包括模型权限不足、账号或 Key 被限制，以及请求 IP 不在允许范围内。

处理方法： 检查 Key 对应的分组、模型权限和 IP 限制。如账号余额或 Key 状态异常，请先在用户中心处理。

404 Not Found

请求的地址或资源不存在。通常是 URL 路径、接口名称或模型名称填写错误。

处理方法： 使用用户中心显示的 Base URL，检查接口路径和模型名称，不要自行重复添加路径。

413 Payload Too Large

单次请求内容过大，例如文字、图片、附件或上下文超过了网关或模型允许的最大限制。

处理方法： 缩短上下文、压缩图片、减少附件，或将任务拆成多次请求。

429 Too Many Requests

请求过于频繁、并发过高，或者账号的额度、余额或限额已经用完。

处理方法： 降低请求频率和并发数，等待一段时间后重试，并检查用户中心的余额与限额。

5xx：服务端或上游服务异常

500 Internal Server Error

服务器处理请求时发生内部错误。

处理方法： 稍后重试。如果持续出现，请记录错误时间和完整错误信息后联系我们。

502 Bad Gateway

网关没有从上游服务获得有效响应。可能是上游模型服务异常、网络连接失败或网关配置暂时有问题。

处理方法： 等待几十秒后重试。持续出现时可以联系我们排查。

503 Service Unavailable

服务暂时不可用，常见于服务器过载、维护、排队或上游模型服务不可用。

处理方法： 降低请求频率，等待一段时间后重试。

504 Gateway Timeout

网关等待上游服务响应超时，可能是模型推理时间过长或上游服务响应缓慢。

处理方法： 简化请求内容后重试。持续出现时请联系我们。

524 A Timeout Occurred

Cloudflare 已经连接到源站，但源站没有在规定时间内返回响应。常见原因包括服务器过载、任务处理时间过长或源站服务异常。

处理方法： 稍后重试；如果多次请求都出现 524，请联系我们排查服务器状态。

联系我们时请提供

为了更快定位问题，请提供以下信息：

• HTTP 状态码和完整错误信息
• 出错的大致时间
• 使用的接口和模型名称
• 响应中的 Request ID（如果有）

请勿发送完整 API Key。需要核对 Key 时，只提供开头和结尾各几位即可。