错误响应
请求失败时，API 返回非 2xx 状态码，响应中的 error 包含错误信息。例如：
json
{
"error": {
"type": "api_error",
"message": "请求参数无效"
}
}
根据 HTTP 状态码处理错误，不依赖提示文案进行程序分支判断。排查时记录状态码、响应内容和发生时间；响应头包含 X-Request-Id 时，一并保留请求编号。日志应隐藏 Authorization、数据源凭据及敏感正文。
按状态处理
| HTTP 状态 | 常见原因 | 处理方式 |
|---|---|---|
| 400 / 422 | 参数缺失、类型或格式错误 | 修改参数后重新调用 |
| 401 | Key 缺失、无效或已停用 | 检查鉴权配置 |
| 402 | 余额不足或消费限额限制 | 核对账户及 Key 额度 |
| 403 | 未授权目标 API | 检查 Key 权限 |
| 404 | 任务、文件或资源不存在 | 核对编号及结果有效期 |
| 409 | 任务状态冲突、重复请求冲突 | 查询原任务状态 |
| 413 | 请求体或文件超过限制 | 减小请求体或文件大小 |
| 429 | 请求频率或配额限制 | 按返回提示等待 |
| 5xx | 服务暂时不可用或处理失败 | 判断是否可重试，保留请求编号 |
根据具体接口返回的状态码和错误信息排查。
重试方式
参数和权限错误需要先修改请求或配置。
429 若携带 Retry-After，按该值等待；未携带时使用有上限的退避间隔。网络异常、5xx 或请求超时时，先核对调用记录。
重复提交 POST 会再次发起处理。为每次业务操作保留关联编号；核对原请求后再决定是否重试，避免重复处理与扣费。
定位问题
先在调用记录核对 API、时间、Key 名称、状态与请求编号。确认输入中没有空值、错误 URL、未支持的格式。
联系支持时提供请求编号、时间、接口、已脱敏的请求和错误响应，不提供完整 API Key。