エラーレスポンス
What — コードは分類、ボディが詳細
APIがエラーを返すとき、ステータスコードとは別に、ボディに原因を書いたJSONが入っている。 コードは「どの種類の失敗か」の分類までしか語らないので、原因の特定はボディを読む。
読む順番は3段で固定。
- ステータスコードで責任の所在を分ける — 4xx なら自分のリクエストを直す、5xx なら相手の障害なので待つ
- ボディの
messageとcodeを読む — 形式はAPIごとに違うが、message・code・details の3点セットが定番 - ドキュメントのエラー一覧で
codeを引く — 対処法はここに書いてある
How — GitHub の 422 を読んでみる
必須フィールドを欠いた POST に対する実際の返答。コード（422 = 内容の検証で弾いた）より、ボディのほうがずっと具体的。
{
"message": "Validation Failed",
"errors": [
{ "resource": "Issue", "field": "title", "code": "missing_field" }
],
"documentation_url": "https://docs.github.com/..."
}
「Issue の title が missing_field」＝タイトルを付け忘れた、まで一発でわかる。
エラーボディの形式を標準化する動きもある（RFC 9457「Problem Details」、
Content-Type: application/problem+json）。見かけたら「標準形式に従っているAPI」と読めばいい落とし穴
- 200 なのにボディの中に error が入っているAPIがある。ステータスコードだけで成功判定すると、失敗を成功として保存する事故になる。初見のAPIでは成功時のボディの形も一度目で確かめる
- 4xx をリトライで殴らない。リクエストを直さない限り何回送っても同じ結果。再送してよい 4xx は 429 だけ（レートリミット）
関連
- API — API まわりの地図
- HTTPレスポンスの構造 — ステータスコード・ヘッダ・ボディの3点セットはこちら
- REST — 4xx/5xx の分類の考え方
Table of contents