跳转到主要内容

​
Problem details

非 2xx 响应使用 application/problem+json：
常见稳定码包括 idempotency_conflict、quota_exceeded、join_timeout 以及由 schema、认证、并发和资源状态映射的 problem code。错误码新增时客户端应安全地归入未知错误，而不是失败解析。

​
Run 业务错误

创建 run 成功返回 202 pending。之后的节点/schema/provider 错误会使资源变为 failed、timed_out 或 dead_letter，并写入：
查询和 join 请求本身仍可返回 200。客户端必须同时检查 HTTP 状态与 run.status。

​
SSE 格式与续传

  • 事件在发送前写入 PostgreSQL；
  • sequence 在 run 内从 1 单调递增；
  • 重连时发送最后已处理的 Last-Event-ID，服务端从下一条继续；
  • 客户端按 (run_id, sequence) 去重，处理重复交付；
  • 以 : heartbeat 开头的行是保活注释，应忽略；
  • run 到达 terminal 或 paused 后，服务端关闭流。

​
重试策略

  1. 只对 retryable=true、网络故障、429 和临时 5xx 使用有界指数退避；
  2. 遵守 Retry-After；
  3. 创建 run 重试复用相同 Idempotency-Key 与完全相同请求；
  4. SSE 重连复用最后 sequence，不创建新 run；
  5. 不自动 redrive 确定性 schema/tool 权限错误。
请求 key 相同但 body 不同会返回 409 idempotency_conflict。不要在冲突后随机换 key 并静默重试，否则可能掩盖调用方 bug 并产生重复业务操作。