エラーコード

すべての API エラーには安定した error コードがあります。厳密なハンドリングには error で分岐し、粗い分類には type で分岐してください。また request_id が 存在する場合は必ずログに残してください。サポートが呼び出しを追跡できます。

エラーエンベロープ

OAuth プロトコルエンドポイントは RFC 6749 形式のエラーに従います。

{
 "error": "invalid_request",
 "error_description": "code_challenge_method is required and must be S256"
}

開発者データ API のエラーは同じフラットな error フィールドを保ちつつ、粗い type と追跡可能な request_id を追加する場合があります。

{
 "error": "insufficient_scope",
 "scope": "recipe:publish",
 "type": "auth_error",
 "request_id": "req_..."
}

スキーマ検証はすべてのハンドラーより先に実行されます。ボディやフォームが OpenAPI スキーマに合わないと、validation_error と、問題のあるフィールドを列挙した details 配列が返ります。このエンベロープには type、error_description、 request_id がなく、ハンドラーが返すはずだったコードも現れません。 POST /oauth/token に未知の grant_type を送ると unsupported_grant_type ではなく validation_error に、redirect_uris のない POST /oauth/register は invalid_request ではなく validation_error になります。

{
 "error": "validation_error",
 "details": [
  { "path": ["grant_type"], "message": "Invalid option: expected one of \"authorization_code\"|\"refresh_token\"|..." }
 ]
}

レート制限のレスポンスには、機械が直接処理できるリトライのタイミング情報が 含まれます。

{
 "error": "rate_limited",
 "retry_after_ms": 1200,
 "next_request_at": "2026-06-17T12:00:01Z",
 "hint": "Rate limited. Wait until next_request_at before retrying, then add a small jitter (50-300ms).",
 "agent_instruction": "sleep_until_next_request_at"
}

エラータイプ

主なコード

「タイプ」列はレスポンスが実際に持つ type フィールドです。OAuth プロトコルのボディ （OAuthProtocolError）とハンドラー前のボディ（validation_error、unauthorized）には 存在しないため、該当行はダッシュで示しています。

ログに残すヘッダー

トラブルシューティング手順

invalid_token

ヘッダーが厳密に Authorization: Bearer <access_token> であることを確認して ください。トークンが期限切れまたは失効済みなら、リフレッシュするか、ユーザーに 再度同意を通してください。テストとライブの認証情報は分けて管理してください。 テストクライアントはサンドボックスのデータを返します。

insufficient_scope

エラーボディの scope フィールドを読んでください。そのスコープをクライアントに 申請し、新しい同意を取得してから、新しいトークンでリトライします。

PKCE invalid_request

PKCE は必須で、S256 のみ対応です。code_challenge を含め、 code_challenge_method を S256 に設定し、plain は絶対に使わないでください。

rate_limited

next_request_at または Retry-After ヘッダーまでスリープしてから、小さな ジッターを加えてリトライしてください。密なループでポーリングしないでください。

quota_exceeded

公開クォータは読み取りのレート制限とは別枠です。ソフト降格には X-Quota-Restored-At が含まれます。ハード降格は自動では回復せず、挙動の変更 または審査が必要です。

べき等性のエラー

論理的な公開操作ごとに Idempotency-Key を 1 つ使ってください。同じキーを 同じボディで使い回すと結果が安全に再生されます。異なるボディで使い回すと idempotency_key_reuse が返ります。

validation_error

リクエストはハンドラーに届いていません。details[].path を読み、OpenAPI スキーマに 合わせて各フィールドを修正してから再試行してください。エンドポイント固有のコード （unsupported_grant_type、invalid_scope、invalid_redirect_uri など）は検証を 通ったボディに対してのみ返ります。それらは RFC 6749 形式の error と任意の error_description だけで、やはり type と request_id は持ちません。

関連

• 一貫性プリミティブ — エラーエンベロープ、ページネーション、べき等性、レート制限の規約
• API エクスプローラー — これらのボディとヘッダーを実際に確認する
• API 概要 — エンドポイントの範囲と OpenAPI リンク