错误与限制

所有非 2xx JSON 错误都使用同一个 envelope：

{
  "error": {
    "code": "invalid_request",
    "message": "Request body must be an object."
  }
}

按 error.code 分支处理，不要按 error.message。message 面向开发者，不应直接展示给最终用户。

错误码

HTTP	`error.code`	调用方动作
400	`invalid_request`	修正请求形状、字段值、body size 或 unsupported field。不要原样重试。
400	`invalid_json`	修正序列化或 `Content-Type`。
401	`unauthenticated`	检查 `Authorization`；轮换或重新创建 API token。
403	`forbidden`	检查 API token 是否能访问该 Agent、Thread 或 file。
404	`not_found`	检查 ID 是否存在且对该 API token 可见。
409	`agent_not_published`	发布 Agent 并启用 API access。
409	`service_inactive`	在 mosoo 中重新发布或修复 Agent。
409	`readiness_blocked`	修复 mosoo 中的 Agent readiness 或配置。
409	`idempotency_conflict`	如果原请求仍在处理，按 `Retry-After` 等待；如果 body 不同，使用新 key。
429	`rate_limited`	Back off，并在 `Retry-After` 后重试。
500	`internal_error`	带 backoff 短暂重试；重复失败时记录故障详情。

Idempotency-Key 支持：

规则：

使用 Project key 时，幂等 key 按 Project、method 和 route 隔离，并检查请求体冲突。同一 Project 的密钥共享幂等记录和限流范围，轮换后仍然如此。账号 CLI 凭据使用自身的凭据边界。
同一个 key 搭配同一个请求会 replay 已存响应。
同一个 key 搭配不同请求会返回 409 idempotency_conflict。
第一个请求仍在处理时复用同一个 key 会返回 409 idempotency_conflict。
key 必须非空，且不超过 128 字符。
冲突响应可能包含 Retry-After。

端点级请求和响应详情。

API token 和 Agent access 检查。