跳至主要内容

错误处理与请求追踪

先判断失败阶段,再选择修正、查询或重新发起。

读取错误

标准 /v1 模型接口使用所选协议的错误格式;旧开放端点、控制台和资金查询可能使用不同业务信封,不能用同一解析器硬套所有响应。

OpenAI 格式示意:

json
{"error":{"type":"invalid_request_error","message":"Invalid request"}}

Anthropic 格式示意:

json
{"type":"error","error":{"type":"invalid_request_error","message":"Invalid request"}}

示意只说明结构。实际 message、机器码和扩展字段以原响应为准,不根据示例文本判断程序分支。

状态与动作

HTTP 状态常见原因下一步
400请求格式、参数或输出预算不符合所选配置对照参数表修正,不循环重试同一载荷
401凭证缺失、失效或已吊销检查 Key;不要用浏览器会话替代
402对应余额、额度或会员权益不足先核对当前凭证所属余额;不自动提高预算
403scope、模型授权或身份条件不足检查权限和当前开放范围
404模型不存在、禁用或对应兼容入口未开放刷新目录,检查 ID 与端点
409价格版本改变、幂等冲突或合同冲突按业务码重新确认价格或查询原操作,不随机换键绕过
429限流、并发或窗口额度限制遵循适用 Retry-After;区分未受理与结果未知
503计费合同、身份、供应商或依赖暂不可用查看具体业务码/状态;保留原请求标识

Retry-After 说明等待条件,不自动证明付费 POST 可以安全重放。只有确认原请求未受理且用户决定继续时才重新发起;未知结果先查询。流内错误见流式指南。

保存哪些标识

标识用途
X-Request-ID本次传输与排错关联
X-Acosmi-Request-Id响应提供的消费请求关联,查询原费用
provider/task/operation ID对应上游任务或业务操作,不与前两者互换

到本人请求查询原请求及财务状态。不要把 Key 明文、Cookie 或完整敏感输入写入日志。超时不证明未执行,缺 usage 不证明免费。

使用 Acosmi SDK 的其他业务时,HTTPError、NetworkError、BusinessError、CompliancePollError 另有分类;见SDK 文档。