Errors and limits

所有非 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 支持：

规则：

端点级请求和响应详情。

API token 和 Agent access 检查。