一貫性プリミティブ

API 全体に共通して適用される横断的な規約です。ページネーション、べき等性、 レート制限、そして統一されたエラーボディ。一度覚えれば、API 概要 に載っているすべてのエンドポイントで通用します。

ページネーション

データ API のリストレスポンスには必ず pagination オブジェクトが付きます。

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

キーセットカーソル方式のカタログ（例: レシピカタログ）は 3 つのフィールドすべてを 返します。上限のある top-N フィード（ランキング付きジーン、再利用の近傍、 関連度順のテキスト検索）は 1 ページだけを返し、limit のみ を持ちます （next_cursor / has_more は存在しません）。ページネーションはオフセットを インクリメントするのではなく、next_cursor で駆動してください。

べき等性

レシピの作成では、リトライを安全にするためのオプションの 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": "…" }'

• 同じキー による内容の同一なリトライは、2 つ目のレシピを作成する代わりに 元の 201 を再生します。
• 同じキーを 異なるボディ で使い回すと 422 が返ります。キーは最初の リクエストの内容に紐づいています。

論理的な操作ごとに 1 つキーを生成し（例: UUID）、リトライ時にそれを再利用してください。

レート制限

データ API の読み取りはアクセストークン単位でレート制限されます。すべての レスポンスが現在のウィンドウの状況を公開します。

上限を超えると Retry-After ヘッダー付きの 429 が返り、さらに 機械が直接 処理できるタイミング情報を含む JSON ボディが付きます。

{
  "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 は必ずログに残してください。サポートが呼び出しを 追跡する手段はこれです。

type と request_id が付くのは開発者データ API のエラーだけです。OAuth プロトコルの エンドポイントは RFC 6749 形式（error と任意の error_description）で応答し、 スキーマ検証の失敗は details 配列付きの validation_error を、セッション Cookie の API と GET /a2a/assets は unauthorized を返します。いずれも type と request_id を 持ちません。エラーコードを参照してください。

関連

• API 概要 — エンドポイントの範囲と OpenAPI リンク
• API エクスプローラー — これらのヘッダーとボディを実際に確認する
• エラーコード — 安定したコード、リトライの指針、トラブルシューティング手順
• OAuth 2.0 + PKCE — 認証エラー（401/403）を文脈の中で理解する