开始使用
错误排查
先读状态码和错误信息，再检查地址、Key、分组、额度与请求格式。
保留能定位请求的信息#
先记录请求时间及时区、客户端名称与版本、完整模型 ID、接口路径、HTTP 状态码和错误信息。如果返回了请求 ID，一并保留。不要把密钥、Cookie 或完整敏感提示词放进反馈内容。
常见错误与第一步动作#
以下是常见排查方向，最终以响应正文为准。同一状态码可能有不同原因，尤其是限额、权限和上游错误。
| 现象 | 先检查 | 下一步 |
|---|---|---|
| 400 / 参数错误 | JSON 格式、请求字段、模型与接口是否匹配 | 恢复最小示例，逐项添加参数。 |
| 401 / 认证失败 | Key 是否完整、已撤销或过期，认证变量是否加载 | 重新检查配置，避免反复发送同一无效请求。 |
| 403 / 无权限 | 分组、模型限制、客户端使用规则 | CC-MAX 应使用 Claude Code；确认权限后再试。 |
| 404 / 路径或模型未找到 | 重复的 /v1、错误路径、准确模型 ID | 对照接口说明。 |
| 429 / 限流或额度相关提示 | 错误正文、账户余额、令牌额度、并发请求数 | 按提示降低并发或调整额度；不要立即密集重试。 |
| 5xx / 服务端或上游错误 | 是否集中在某模型、是否短时间持续出现 | 保留失败样本，延后少量重试；持续失败则整理反馈。 |
| 超时 / 中途断开 | 网络、客户端超时、流式设置与已有日志 | 先确认原请求结果，再决定是否重发。 |
余额充足为什么仍然失败#
检查单把 Key 的额度、有效期和模型限制，再检查所选分组。账户余额并不能覆盖令牌本身的限制。详见余额与费用。
只有某个应用失败#
先对照它的地址填写规则，确认需要根地址还是 /v1 基址。浏览器应用的 Failed to fetch 也可能与网络、HTTPS 或跨域有关；不要把 API Key 放到公开网页前端来绕过问题。Codex 和 Claude Code 分别按专用教程配置。
何时重试#
如果图片或其他长任务返回 HTTP 524，先按下面的长任务步骤核对，再决定是否重发。增加客户端等待时间不能保证消除服务链路返回的超时。
认证错误、模型不存在和参数错误应先修正配置。临时限流或服务故障可以延迟后少量重试；如果响应给出 Retry-After，按该提示等待。为自动重试设置次数上限，并避免应用、SDK 和外层任务同时多层重试。
超时后的同一 POST 请求可能已经处理完成。图片、长输出和有外部动作的工作流尤其应先核对结果，避免重复任务。持续失败时，使用反馈模板整理一份脱敏样本。
524 或长任务超时后怎样核对#
- 记录请求时间及时区、完整模型 ID、等待时长、HTTP 状态与脱敏错误正文；从响应或客户端详情中保留请求 ID（如有）。
- 检查当前客户端是否已经收到或保存了结果，再到使用日志查找对应时间和模型的记录，并核对费用与余额变化。
- 如果结果、日志或费用状态仍不明确，先保留证据并按问题反馈核实，不要立即重复提交同一任务。
仅凭 524 或客户端超时，不能确定任务未执行、不会产生费用或会自动退还。重新发送 POST 也不保证沿用原任务或免除重复费用。