接入排查

排查前先保留这些信息

• 请求时间
• HTTP 状态码
• 错误码或错误消息
• request_id
• 使用的模型名称
• 触发问题的客户端类型，例如 SDK、Codex、Claude Code 或 curl

鉴权失败

常见现象：

• 返回 401 或 403
• 提示 token 无效、缺失或已停用

优先检查：

• 请求头是否使用 Authorization: Bearer YOUR_API_KEY
• 对应 Token 是否已经停用、过期，或被替换
• Token 是否已经耗尽额度
• 当前请求是否被 Token 的模型限制拦住

模型名称错误

常见现象：

• 返回 model not found
• 请求能到达接口，但模型无法解析

优先检查：

• model 是否使用了当前站点允许调用的名称
• 是否直接照抄了文档示例值
• 是否存在模型映射，导致外部调用名与渠道原始模型名不同
• 当前 Token 是否有权限访问这类模型

请求体格式错误

常见现象：

• 返回 400
• 错误提示指向缺少字段或 JSON 结构不合法

优先检查：

• 请求体是否至少包含 model 和 messages
• Content-Type 是否为 application/json
• JSON 是否有效
• SDK 或中间件是否额外改写了请求体

超时、限流或偶发失败

常见现象：

• 返回 429
• 返回超时
• 同一批请求中偶发失败

优先检查：

• 是否在短时间内发送了过多请求
• 当前模型或 API Key 是否存在并发、配额或速率限制
• 服务端日志里是否记录了对应的 request_id
• 是否需要做重试、退避或请求削峰

限制信息入口见 配额与速率限制。

仍然无法定位时

如果以上检查后仍未定位问题，请整理以下最小信息后再联系支持：

1. 失败时间和时区
2. request_id
3. 使用的 endpoint 与模型名称
4. 已脱敏的最小请求示例
5. 同一问题是否可以稳定复现

如果控制台已经开放使用日志，优先结合 request_id 和日志记录一起定位。