AI API 的 HTTP 错误、failed、incomplete、refusal 和 moderation flagged 有什么区别？

结果 发生位置 是否可能有 HTTP 2xx 是否可能有部分输出 首要读取字段 默认处理方向

-- --- --- --- --- ---

HTTP 错误 请求/协议层 否 通常没有有效响应对象 状态码、错误类型、request ID 按 4xx/5xx 分类

failed 响应对象生命周期 可以 视平台与事件而定 status、error.code、error.message 记录失败并判断是否可重试

incomplete 响应生成生命周期 可以 是 status、incompletedetails.reason 不标记成功，按原因恢复

refusal 模型输出内容 可以 拒绝文本本身是输出 content part 的 type=refusal 安全呈现或请求合规改写

moderation flagged 独立分类接口 可以 返回分类分数/布尔结果 results[].flagged、categories 应用策略决策与审计

状态码只说明这次 HTTP 交换；对象状态描述异步或生成任务；内容 part 描述模型实际输出；审核结果描述分类。代码结构应保留这四个层次，避免后一个字段覆盖前一个字段。

HTTP 4xx 通常表示客户端请求、认证、权限、限额或参数存在问题。常见例子包括 JSON 无法解析、字段类型错误、模型不存在、上下文超限、凭据无效或权限不足。除 408、409、429 等具备特定临时语义的情况外，重复发送完全相同的 4xx 请求通常不会自行恢复。

HTTP 5xx 表示服务端或上游暂时无法完成请求，更可能适合有限重试。但重试仍需要指数退避、随机抖动、总时长上限和幂等边界。对于创建任务、执行工具或产生外部副作用的接口，网络断开后不能假定服务端什么都没做；应通过 request ID、幂等键或对象查询确认。

错误记录应保存脱敏后的状态码、错误类型、错误码、模型、端点、SDK 版本和 request ID。不要记录完整 API key、Authorization 头、用户隐私输入或未经处理的文件内容。面向用户的消息也不应直接暴露内部堆栈。

HTTP 2xx 不等于模型任务一定完整成功。平台可以成功返回一个状态为 queued、inprogress、failed 或 incomplete 的对象；客户端必须继续读取对象状态，不能只检查 response.ok。