错误码与重试

Tapapi 的公开 API 以 OpenAI 兼容错误格式为主。生产代码不要只看 HTTP 状态码，还要读取 error.code、error.message 和响应头里的 X-Oneapi-Request-Id：状态码告诉你大类，error.code 才能区分余额、参数、上游异常和内容拦截，request_id 用于后续排障和对账。

HTTP	含义	处理
200	请求成功	文本读取 `choices`，图片读取 `data[].url` 或 `data[].b64_json`
400	请求字段错误	不重试，按 `error.message` 修正参数
401	API Key 缺失或无效	检查 `Authorization: Bearer sk-xxx`
403	账户、权限、余额或订阅不足	重点看 `error.code`，余额不足通常是 `insufficient_user_quota`
413	请求体过大	缩小图片、文件或请求体
422	内容或参数被上游拒绝	调整 prompt、图片或模型参数
429	限流或上游负载饱和	降并发，指数退避后有限重试
临时 5xx	平台或上游临时异常	只做有限重试，并记录请求信息
504 / 524	长时间无结果或网关超时	不要立即盲重试，先看超时处理

错误响应格式：

{
  "error": {
    "message": "... (request id: 20260609...)",
    "type": "new_api_error",
    "code": "invalid_request"
  }
}

响应头也会带请求标识：

X-Oneapi-Request-Id: 20260609...

部分错误可能没有稳定的 error.code，或者 code 为空。生产代码应同时记录 HTTP 状态码、error.type、error.code、error.message 和 request_id，不要只依赖单个字段。

常见 code

code	常见含义	建议
`invalid_request`	参数缺失、格式错误或接口不支持该字段	不重试，修请求
`read_request_body_failed`	请求体读取失败或过大	不重试同一请求，缩小请求体
`model_not_found`	模型不存在或当前分组不可用	检查模型名和账户权限
`insufficient_user_quota`	余额、订阅或令牌额度不足	充值、升级或切换账户
`pre_consume_token_quota_failed`	预扣令牌额度失败	不重试，检查 API Key 额度或余额
`sensitive_words_detected`	命中敏感词或内容策略	修改 prompt 或输入内容
`prompt_blocked`	上游内容安全拦截	修改 prompt、图片或切换模型
`bad_response_status_code`	上游返回异常状态	可按 5xx/429 策略有限重试
`bad_response`	上游响应格式不符合预期	保留响应和 request id 排障
`bad_response_body`	上游响应体不可解析	通常不要重复重试，保留响应排障
`empty_response`	上游空响应	有限重试一次，仍失败则排障
`api_not_implemented`	当前接口未实现或尚未开放	换已开放接口，不重试

余额不足不要写死判断 402。当前后端的余额、订阅和令牌额度不足主路径通常返回 403，并通过 error.code: "insufficient_user_quota" 表达。

重试建议

以下是客户业务侧的重试建议，不等同于 Tapapi 平台内部的通道重试策略。平台内部可能为了换通道做有限重试，但你的业务代码仍不应自动重试鉴权、余额、权限和参数错误。生产代码建议按三类处理：

类型	包含	处理
不重试	400 / 401 / 413 / 422、余额不足、权限不足、`model_not_found`、`api_not_implemented`	修请求、充值、换模型或联系支持
可有限重试	429、临时 5xx、`empty_response`、网络中断	指数退避，最多 1-2 次，并带随机抖动
先确认再重试	504 / 524、前端 timeout、图片 URL 下载失败、流式中断	先查业务记录、用量日志和保存状态，确认没有有效结果再补跑

推荐退避节奏：

第 1 次失败 -> 等 1-2 秒
第 2 次失败 -> 等 3-5 秒
第 3 次失败 -> 停止自动重试，记录并告警

批量任务要加随机抖动，避免所有 worker 同时重试。

生产日志必须记录

字段	用途
`request_id`	由 `X-Oneapi-Request-Id` 返回，排障第一定位字段
业务 `task_id`	和你的订单、图片、用户操作关联
模型名	排查模型权限、价格、耗时和上游状态
HTTP 状态码	判断错误大类
`error.code` / `error.message`	判断是否重试、是否余额不足、是否内容拦截
请求摘要	保存脱敏后的 prompt、尺寸、`n`、输入图片数量
返回摘要	文本 token、图片 `data.length`、`url` / `b64_json` 类型

图片返回异常

现象	建议
`data` 为空	当作生成失败处理，记录模型、请求时间和业务 `task_id`
只有 `b64_json`	解码后转存，不要只读取 `url`
返回张数少于请求 `n`	按实际返回张数处理，缺失图片单独补跑
返回张数多于请求 `n`	业务只处理需要的数量；当前公开主路径计费会封顶到请求的 `n`
URL 下载失败	后端服务重试下载；仍失败时保留原始返回和错误码
`error.type: "image_proxy_error"`	可能是签名过期、上游下载失败、白名单校验失败或代理取图超时，尽快转存到自有存储

任务类错误

当前文本和普通图片请求优先按同步接口理解。视频和异步任务按受控开放能力处理，错误响应可能不是完全相同的 OpenAI 兼容格式，可能直接返回 code、message、status_code。业务侧仍应统一记录：

业务 task_id
Tapapi 返回的 request_id
HTTP 状态码
error.code
error.message
模型名和请求时间

限流细则放在限流与并发，超时细则放在超时处理。

稳定性

成本与发布

常见 code

重试建议

生产日志必须记录

图片返回异常

任务类错误

​常见 code

​重试建议

​生产日志必须记录

​图片返回异常

​任务类错误

常见 code

重试建议

生产日志必须记录

图片返回异常

任务类错误