模型 API
处理错误、限流和未知结果
分清可重试读取、可幂等恢复写入和需要用户修正的请求。
先识别失败发生在哪一步
连接建立、HTTP 拒绝、任务业务失败和输出下载失败有不同恢复方式。保存安全的 requestId、状态码和机器错误码用于排查；不记录 Key、用户完整输入和带身份信息的 URL。
| 现象 | 应做什么 | 不应做什么 |
|---|---|---|
| 400 / 422 | 按字段错误修正模式、素材或规格 | 原样高速重试 |
| 401 | 检查 Key 完整性、失效或到期 | 在日志打印密钥确认 |
| 402 | 检查额度与当前价格准入 | 更换用户身份规避计费 |
| 403 | 检查服务范围、冻结和权限 | 自动扩大 scope |
| 404 | 核对原模型、任务或素材 ID | 新建任务“找回”旧结果 |
| 409 | 区分幂等冲突、处理中与资源冲突，查询原状态 | 用同键发送不同正文 |
| 429 | 遵守 Retry-After，限制并发并退避 | 用多个 Key 绕过限制 |
| 503 / 504 | 判断请求是否已经受理；有任务 ID 就继续查询原任务 | 无条件换键重提 |
| 查询返回 failed | 停止轮询，读取业务错误；明确发起新动作才重试生成 | 把 HTTP 200 当作生成成功 |
| SSE 提前断开 | 标记部分内容、保留用户输入 | 把截断内容作为完整结果 |
写入结果未知
响应丢失不等于服务端没有执行。公开操作声明支持幂等时，用同身份、同业务键、同正文恢复；已经取得 ID 时优先查询。未声明幂等的操作不自动重放。
API Key 创建不提供秘密找回，遵循 创建结果不确定。一次性会话交换与模型生成不是同一种重试协议。
计费与等待
请求可能先进行额度预占，再按最终执行事实结算。页面报价不是永久锁定价格；最终由真实请求命中的规则决定。上传成功、任务受理和模型完成是三个不同事实。
缩短客户端超时不会加速执行，也不会自动取消已受理任务。为每条链设置总等待预算和最大退避时间；不要对网络问题无限轮询。