错误与排障
根据错误来源和 HTTP 状态定位调用问题，并选择安全的恢复方式。
当 API 请求失败时，先保存 HTTP 状态码和经过脱敏的错误信息，再判断问题来自请求、认证、模型还是服务端。不要在没有确认原因时持续重试同一个请求。
先保护凭证和客户数据
排障记录中不要包含完整 API Key、Authorization 或 x-api-key Header、Cookie、密码、完整 Prompt、客户文件或其他敏感信息。
先判断错误来自哪里
| 错误来源 | 常见表现 | 建议动作 |
|---|---|---|
| 请求内容 | JSON 无效、缺少字段、参数类型错误、文件格式不符合要求 | 根据错误信息修正请求，不要原样重试 |
| 认证与权限 | API Key 缺失、无效，或者当前 Key 无权访问目标模型 | 检查 Base URL、对应协议的认证 Header、Key 状态和模型权限 |
| 模型与资源 | 模型 ID、任务 ID 或请求路径不存在 | 从模型广场重新复制 ID，并核对资源所属账户 |
| 平台或上游 | 服务暂时不可用、处理超时或上游返回错误 | 保存诊断信息，有限重试；持续失败时停止请求 |
| 异步任务 | 提交成功后任务失败、长时间处理中或结果不可用 | 先查询原任务状态，避免直接重复创建任务 |
同一次失败可能同时包含多个线索。例如 404 既可能是端点写错，也可能是模型或任务不存在，应结合最终请求 URL 和错误正文判断。
HTTP 状态速查
| HTTP 状态 | 常见含义 | 建议恢复方式 |
|---|---|---|
400 | 请求格式、参数或输入内容有误 | 修正请求后重新发送 |
401 | API Key 缺失、无效，或者认证 Header 不符合接口要求 | 检查对应协议的认证方式；必要时创建并替换新 Key |
403 | 当前账户、Key 或模型的使用范围不满足请求 | 检查账户状态、令牌限制和模型权限 |
404 | Base URL、端点、模型或任务不存在 | 核对最终 URL、模型 ID、任务 ID 和所属账户 |
429 | 请求频率、并发、额度或服务容量受到限制 | 停止高频请求，根据实际错误信息降低负载并稍后重试 |
500–599 | 平台、网关或上游服务暂时无法完成请求 | 保存诊断信息，使用有限次数的退避重试 |
这些状态只用于快速判断方向。不同协议和上游返回的程序错误码可能不同，应结合 HTTP 状态、实际错误正文和对应 API Reference 判断原因。
推荐排障流程
记录失败现象
保存请求时间和时区、Method、Path、模型 ID、HTTP 状态，以及经过脱敏和长度限制的错误信息。响应中存在 Request ID 时一并保存。
核对地址和认证
使用 https://api.agtcloud.cn/v1 作为 Base URL，并确认最终 URL 没有重复的 /v1/v1。OpenAI 兼容接口通常使用 Authorization: Bearer your-api-key；其他协议应检查对应 Reference 要求的认证 Header。
核对模型和请求内容
确认模型 ID 来自当前账户可见的模型列表；再检查 Content-Type、JSON、必填字段、文件类型和输入大小。
判断是否适合重试
400、401、403 和明确的资源不存在问题应先修复。临时网络或 5xx 故障可以有限重试，并逐步增加等待时间。
准备脱敏信息
如果问题持续存在，整理最小复现步骤和诊断信息。不要为了排障复制完整 Key、客户 Prompt、文件或未脱敏响应。
安全地处理重试
- 普通只读请求遇到临时故障时，可以采用有限次数的退避重试。
- 参数、认证和权限问题只有在修复原因后才应再次发送。
- 创建任务、调用外部工具或其他可能产生副作用的请求，在重发前先确认原请求是否已经生效。
- 异步请求应优先查询原任务 ID，不要仅因为客户端超时就创建重复任务。
- 设置最大重试次数和总等待时间；持续失败时停止自动请求并保留诊断信息。
准备哪些排障信息
| 信息 | 示例或说明 |
|---|---|
| 发生时间 | 包含日期、时间和时区 |
| 请求位置 | Method 和 Path，不包含完整 API Key |
| 调用目标 | 模型 ID；异步任务可附任务 ID |
| 响应结果 | HTTP 状态和脱敏错误信息 |
| 请求特征 | 是否流式、是否包含工具、是否为异步任务 |
| 客户端环境 | SDK 名称与版本、运行时版本、最小复现步骤 |
| 追踪信息 | 响应中存在时保存 Request ID |
需要查询程序错误码和处理建议时，请查看错误码参考。仍未解决时，可以继续查看 Request ID 和 FAQ。首次接入问题请重新核对快速开始和 API Key、Base URL 与认证。