错误、幂等与 SSE

Problem details

非 2xx 响应使用 application/problem+json：

{
  "type": "about:blank",
  "title": "Quota Exceeded",
  "status": 429,
  "detail": "tenant queued-run quota exceeded",
  "code": "quota_exceeded",
  "request_id": "01J...",
  "retryable": true
}

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

Run 业务错误

创建 run 成功返回 202 pending。之后的节点/schema/provider 错误会使资源变为 failed、timed_out 或 dead_letter，并写入：

{
  "status": "failed",
  "error": {
    "code": "invalid_update",
    "message": "...",
    "retryable": false
  }
}

查询和 join 请求本身仍可返回 200。客户端必须同时检查 HTTP 状态与 run.status。

SSE 格式与续传

GET /v1/runs/{run_id}/stream
Accept: text/event-stream
Last-Event-ID: 17

id: 18
event: node_completed
data: {"id":"...","run_id":"...","sequence":18,"kind":"node_completed","data":{},"created_at":"..."}

• 事件在发送前写入 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 权限错误。