错误处理
区分协议错误、请求校验、业务响应、等待超时与流式错误。
先判断 HTTP 状态码和调用的端点，再解析错误体。POCO 的不同接口有不同响应协议，不能只依赖错误消息文本。
错误体按端点区分
Chat Completions 的业务错误：
{
"error": {
"message": "错误描述",
"type": "invalid_request_error",
"param": null,
"code": null
}
}Messages、会话和运行接口的业务错误：
{
"type": "error",
"error": { "type": "invalid_request_error", "message": "错误描述" }
}普通 Schema 校验失败为 HTTP 422，使用框架响应：
{
"detail": [
{ "loc": ["body", "messages"], "msg": "校验说明", "type": "校验类型" }
]
}登录 Token 端点的业务及校验错误使用 type=error 格式，并带 Cache-Control: no-store、Pragma: no-cache。Office Mode、公开发布页、Key 管理、人工输入和 WebHook 管理的业务响应使用 {code,message,data}；它们的 Schema 校验失败仍需按 detail 解析。
状态与处理
| HTTP 状态 | 典型原因 | 处理 |
|---|---|---|
| 400 | 无有效 user 输入、session_id 不是 UUID、业务状态不允许 | 修正请求 |
| 401 | 凭证缺失、失效、过期，或 Key 所属用户不可用 | 更换凭证或检查账号 |
| 403 | scope 不足、会话归属或绑定 Key 不匹配 | 检查权限与创建任务时的 Key |
| 404 | 资源不存在，或用运行结果接口查询非后台 Run | 检查 ID、环境和接口适用范围 |
| 409 | 会话忙、幂等模式冲突、连接器操作结果未知 | 先查当前状态；结果未知时先查外部系统 |
| 413 | 请求或附件过大 | 缩小材料或检查入口限制 |
| 422 | 请求字段、枚举或组合不符合 Schema | 根据 detail 修正 |
| 429 | 后台数量、轮询频率或待处理输入超过限制，或输入受理繁忙 | 遵循 Retry-After |
| 500 / 502 | 内部处理或依赖服务异常 | 保存标识，确认状态后有限重试 |
| 503 | 后台容量不可用或队列已满 | 按响应提示等待容量恢复 |
| 504 | 普通非流式等待超时 | 查询已有任务，避免重复创建 |
空 messages 为 422；非空但没有 user 消息或最后一条 user 内容无有效输入为 400。metadata.session_id 的 UUID 解析错误属于业务 400。background=true 与 stream=true 组合、缺少后台幂等键、无效 Base64，或普通请求携带 background_payload，属于 Schema 422。
非流式等待超时
普通非流式请求最多等待 300 秒。HTTP 等待超时不代表执行已经取消。
Messages 的等待失败响应保留 X-Session-Id 和 X-Run-Id；504 另带 Retry-After: 5。Chat Completions 的错误响应不保证这些标识头，也没有相同的 Retry-After 契约。接入 Chat 时应预先保存业务幂等键，已有会话则保存 session_id，不能把 Messages 的错误头规则套用过来。
耗时任务可以使用 SSE，或使用 Messages 后台模式获取 Run ID 后轮询。后台结果查询 只适用于后台 Run，普通 Run 的状态应结合会话与事件查看。
流式错误
建立连接前仍返回普通 HTTP 错误。连接建立后，Messages 使用命名事件：
event: error
data: {"type":"error","error":{"type":"api_error","message":"错误描述"}}收到该事件后标记失败，不继续等待正常 message_stop 或结构化 result。
Chat Completions 使用 data 帧，随后发送结束标记：
data: {"error":{"message":"错误描述","type":"api_error"}}
data: [DONE][DONE] 表示流结束，不代表成功；客户端需要记录前面的 error。网络断开不等于错误事件，应查询已有任务状态，不能直接假定运行失败。
幂等与记录
同一次业务请求重试复用 idempotency_key ；新的操作使用新键。普通首次创建也支持幂等，续聊按会话复用已有运行；后台请求按同一 Key 查询原 Run。接口不比较全部请求内容，不要给不同业务请求复用同一键。
记录状态码、错误类型和可获得的会话、运行、业务请求标识。避免记录凭证或敏感附件。自动重试应有上限，并先区分参数问题、容量问题与运行状态未知。