状態、種類、発生事例を分ける
RFC 9457はapplication/problem+jsonを定義します。安定した問題の種類と、その事例に合う説明を使います。翻訳された文章の解析をクライアントの判断条件にしないでください。statusを含める場合は実際のHTTP状態と整合させます。
| 状態 | HTTP上の意味 | 検討する対応 |
|---|---|---|
| 400 | 不正なリクエスト | 修正してから再度送る。 |
| 401 | 有効な認証情報がない | 認証情報と指定の方式を確認する。 |
| 403 | 理解したが拒否された | 権限を確認する。繰り返しても権限は得られない。 |
| 503 | サービスが一時的に利用不能 | 操作が許す場合だけ、待機と再試行を制限して行う。 |
失敗時の経路も設計する
- コード、形式、推奨対応を文書化します。空の応答、ゲートウェイの非JSON、接続切断、タイムアウトも試験します。
- 入力と権限はサーバーで検証します。既知の失敗を扱いつつ未知の障害を隠さず、業務上の失敗を成功応答で覆い隠さないようにします。
- サポートが使える相関IDを返します。スタック、内部クエリ、パスワード、トークンを公開応答に含めません。
意味のある場合だけ再試行する
5xxは無制限の再試行を許可しません。契約、操作状態、冪等性、全体期限を組み合わせて判断します。不具合は機密を除いた最小事例で報告し、修正後は元の事例と関連するアクセス拒否も確認します。
一次資料
APIエラーは、情報漏洩を防ぎつつ、適切な対応を促すものであるべきである。
HTTPステータスは初期カテゴリを提供するが、クライアントは安定したタイプと有用な詳細情報を必要とする場合がある。RFC 9457は一般的な問題構造を記述しているが、内部トレースや機密データの公開を正当化するものではない。
- 永続的な拒否、修正可能な入力、一時的な障害を区別する。
- 重要なエラーごとに、タイプ、ステータス、およびクライアントが取り得る対応を文書化する。
- レスポンスに機密情報や不要なペイロードが含まれていないことをテストする。
一次資料：IETF RFC 9457 — Problem Details for HTTP APIs. 関連する方法：実践ガイドを読む.
API再試行：経路全体の時間を数える
回数上限と全体期限を定めます。
架空の学習用事例です。数値はCIEや顧客の実績ではありません。
架空の4呼出しは各250ミリ秒以内、待機は100、200、400。ジッター、接続、待ち行列、ローカル検証は除きます。
- 総試行数
- 41 + 3
- 待機合計（ms）
- 700100 + 200 + 400
- モデルの予算（ms）
- 17004 × 250 + 700
| 段階 | 呼出し上限（ms） | 次の待機（ms） |
|---|---|---|
| 試行1 | 250 | 100 |
| 試行2 | 250 | 200 |
| 試行3 | 250 | 400 |
| 試行4 | 250 | 0 |
| 合計 | 1000 | 700 |
- 呼出し時間1,000
- 待機の合計700
- 全体の期限（ms）1,500
結論を出す前の確認
- 1,000 + 700 = 1,700は期限1,500ミリ秒を超えます。
- 全体期限を伝え、効果の重複を防ぎます。タイムアウトは遠隔処理の取消しを証明しません。
再試行の時間予算を試す
n × T + W × (2^(n−1) − 1)
関連する方法：実践ガイドを読む.
APIエラー：型・状態・証拠
この言語版の詳しい参照メモは英語で提供しています。
Handle an error without parsing its sentence
An API client may receive a translated title, missing member or unfamiliar extension. Preserve decisions based on the documented type and HTTP status, then connect a safe action to the context.
- Compare received status and JSON status without silently replacing either.
- Test absent type, string status instead of a number, and an unknown extension.
- Separate person-facing text, business code and occurrence reference.
Explore problem types and eight fictional responses →
IETF · M. Nottingham, E. Wilde, S. Dalal · RFC 9457 · July 2023 · obsoletes RFC 7807 · §3.1, §3.2, §4.2, §5