エラーと再試行

エラーレスポンス

JSON API の失敗は次のエンベロープを使います。

{
  "error": {
    "code": "entity_not_found",
    "message": "Catalog entity not found",
    "requestId": "request-id-when-available"
  }
}

HTTP ステータスと安定した code で分岐してください。message は開発者向けの表示やログに使います。より具体的な文言に変わることがあります。requestId は任意で、サービス障害を報告するときに役立ちます。

実際の例:

GET /api/v1/songs/{id}

未送信

ステータスの目安

ステータス	意味	クライアントの対応
`400`	クエリ、ルートの値、JSON、バッチ ID が不正	リクエストを直して再送する。
`401`	セッションが必要	ログインし、ブラウザーの認証情報を送る。
`403`	オリジン、検証、アカウント、権限の確認に失敗	リクエストの前提を直すか、必要な操作を利用者に示す。
`404`	サーバー、リソース、エンティティ、ビュー、リレーション、ファイルが見つからない	カタログを更新するか、見つからない項目を除く。
`409`	バージョン、冪等性、状態の衝突	リソースを読み直し、最新版に変更を適用する。
`413` / `415`	リクエストが大きすぎる、または未対応のメディアタイプ	本文を小さくするか、宣言されたコンテンツタイプを使う。
`422`	本文のフィールドが検証に失敗	レスポンスが示したフィールドを直す。
`429`	レート制限または割り当てに達した	`Retry-After` があれば従い、バックオフする。
`500`	Worker の予期しない失敗	冪等な読み取りをバックオフして再試行する。
`502`	上流またはプロバイダーのプロジェクションが失敗	読み取りをバックオフして再試行し、`X-Request-Id` を保持する。
`503`	データベース、カタログ、ID、ストレージが利用できない	安全な読み取りをバックオフして再試行する。

未知のエラーコードは中身のわからない失敗として扱います。ログには残し、利用者向けの挙動はステータスの区分で決めてください。

再試行の方針

GET と HEAD は、ネットワーク障害、408、429、一時的な 5xx のあとに安全に再試行できます。ジッター付きの指数バックオフを使い、Retry-After に従い、試行回数に上限を設けてください。一時的な失敗のあとは現在のエイリアスを読み直してください。再試行が成功するまでに現在のカタログが変わっていることがあります。

変更系のリクエストには操作ごとの規則が必要です。エンドポイントが冪等性を定めているか、操作を繰り返しても安全な場合にだけ再試行してください。アップロードの予約には Idempotency-Key が必要で、同じキーを異なるメタデータで再利用すると 409 idempotency_conflict が返ります。

よくあるカタログの失敗

route_not_found: 最上位のパスが公開 API のルートではありません。
server_not_found: server クエリの値が有効ではありません。
resource_not_found: 選んだカタログマニフェストにリソースがありません。
entity_not_found: リソースはありますが、要求した ID がありません。
view_not_found または relation_not_found: マニフェストに要求したビューやリレーションが定義されていません。
release_not_found: 上級者向けの明示的なリクエストが、利用できないリリース ID を使いました。

直接エイリアスは現在のデータを使い、リリース ID は不要です。ビルドで過去のリリースを固定する必要がある場合はサーバー単位の上級者向け契約を参照してください。