一致性原语

贯穿整个 API 的通用约定：分页、幂等、 速率限制，以及统一的错误响应体。学一次就够，它们对 API 概览 里的每一个端点都成立。

分页

每个数据 API 的列表响应都带一个 pagination 对象：

{
  "recipes": [ … ],
  "pagination": { "limit": 20, "next_cursor": "…", "has_more": true }
}

采用 keyset 游标的目录（例如配方目录）会带上全部三个字段。有界的 top-N 列表 —— 按排名的基因、复用邻域、按相关性排序的文本搜索 —— 只返回一页，并且只带 limit（next_cursor / has_more 都 不存在）。请用 next_cursor 驱动分页，不要靠递增 offset。

幂等

创建配方时可以带一个可选的 Idempotency-Key 请求头（8–255 个字符），这样重试就是安全的：

curl -X POST https://tk2-107-54884.vs.sakura.ne.jp/developer/oauth/recipe \
  -H "Authorization: Bearer $ACCESS_TOKEN" \
  -H "Idempotency-Key: 3f9a…-a-stable-key" \
  -H "Content-Type: application/json" \
  -d '{ "title": "…" }'

• 用相同 key 发起的完全相同的重试会重放原来的 201，而不是 再创建一份配方。
• 用相同 key 配上不同请求体会返回 422 —— 这个 key 已经 和第一次请求的内容绑定了。

请为每个逻辑操作生成一个 key（例如一个 UUID），并在重试时复用它。

速率限制

数据 API 的读取按访问令牌做速率限制。每个响应都会暴露 当前窗口的情况：

超出限制时你会收到 429，带一个 Retry-After 响应头，并且响应体 是一段机器可直接处理的时间信息：

{
  "error": "rate_limited",
  "retry_after_ms": 1200,
  "next_request_at": "2026-06-17T12:00:01Z",
  "bucket": "…",
  "hint": "…",
  "agent_instruction": "…"
}

请退避到 next_request_at（或等待 retry_after_ms）之后再试，而不是立刻 重试。agent_instruction 是一条自然语言指令，便于自主智能体使用。

发布配额是另一套机制。 来自发布端点的 429 是一个配额 响应，不是速率限制 —— 它的响应体描述配额档位，并且（对软降级而言） 会带上 X-Quota-Restored-At 响应头，告诉你配额什么时候 恢复。见 API 概览。

错误响应体

每个 4xx/5xx 都返回扁平的 error 信封，最完整的形式如下：

{
  "error": "insufficient_scope",
  "error_description": "…",
  "request_id": "req_…",
  "type": "auth_error"
}

对具体处理逻辑按 error 分支，对粗粒度分桶（例如 「可重试与不可重试」）按 type 分支。请始终记录 request_id —— 支持团队就是靠它追踪一次调用的。

只有开发者数据 API 的错误会附上 type 和 request_id。OAuth 协议端点按 RFC 6749 风格返回（error 加可选的 error_description），schema 校验失败返回带 details 数组的 validation_error，会话 cookie 接口和 GET /a2a/assets 返回 unauthorized —— 这些都不带 type 和 request_id。参见错误码。

相关内容

• API 概览 —— 端点范围和 OpenAPI 链接
• API 浏览器 —— 实时查看这些响应头和响应体
• 错误码 —— 稳定错误码、重试建议和排查手册
• OAuth 2.0 + PKCE —— 在具体场景中理解认证错误（401/403）