🐡
WebAPIにおけるエラーの表現方法をわかりやすく解説
0.はじめに
WebAPIを設計・開発するときに避けて通れないのが「エラー処理」。
クライアントが「何が起きたのか」を正しく理解できるように設計することは、ユーザー体験や保守性に直結します。
この記事では、初心者の方でも理解できるように 「WebAPIにおけるエラーの表現」 を整理します。
1. ステータスコードでエラーを表現する
WebAPIでは、まず HTTPステータスコード で結果を伝えます。
- 200系 → 成功
- 400系 → クライアントの入力ミス
- 500系 → サーバー側のエラー
特に以下はよく使われます：
| ステータスコード | 意味 | 例 |
|---|---|---|
| 400 | Bad Request（リクエストが不正） | パラメータ不足 |
| 401 | Unauthorized（認証エラー） | トークンなし |
| 403 | Forbidden（権限不足） | 管理者のみ閲覧可 |
| 404 | Not Found（リソースなし） | ユーザーIDが存在しない |
| 500 | Internal Server Error | サーバー障害 |
2. エラーの詳細をクライアントに返す
ステータスコードだけでは不十分です。
例えば「400 Bad Request」でも、何が間違っていたのかが分からなければ修正できません。
そのため、JSON形式で詳細を返すのが一般的です。
{
"error": "invalid_parameter",
"message": "email フィールドは必須です"
}
3. エラー詳細情報には何を入れるべきか
最低限、以下の情報を含めると親切です。
- エラーコード（機械判別用、英字スネークケースなど）
- メッセージ（人間向けに何が悪いのか）
- フィールド名（フォーム入力の場合）
- トラッキングID（サーバーで調査するときのキー）
例：
{
"error": "invalid_request",
"message": "パラメータ 'age' は数値である必要があります",
"field": "age",
"trace_id": "abc123xyz"
}
4. エラーの際にHTMLが返ることを防ぐ
初心者がハマりがちなのがこれです。
サーバーのデフォルト設定で、エラー時に HTMLのエラーページ が返ってしまうケースがあります。
→ APIとしては必ず JSONレスポンス を返すようにミドルウェアや設定で統一しましょう。
例（悪い例）：
<html><body>500 Internal Server Error</body></html>
例（良い例）：
{
"error": "internal_error",
"message": "サーバー内部でエラーが発生しました"
}
5. メンテナンスとステータスコード
システムメンテナンス中にどう応答するかも重要です。
- 503 Service Unavailable を返す
-
Retry-Afterヘッダーで「いつ復旧するか」を伝える
HTTP/1.1 503 Service Unavailable
Retry-After: 3600
6. 意図的に不正確な情報を返したい場合
セキュリティ観点から、あえて情報をぼかすケースもあります。
- 認証エラー時に「ユーザーIDが存在しない」とは返さず、401 Unauthorized に統一する
- SQLエラーなど内部情報は返さず「internal_error」とだけ返す
これは「攻撃者に手がかりを与えない」ための設計上の工夫です。
7. おわりに
さいごに、今回学んだことのサマリーです。
- ステータスコードで大枠を示し、JSONで詳細を返す
- エラーJSONには エラーコード・メッセージ・フィールド名・トレースID を入れると便利
- HTMLエラーページは返さないように注意
- メンテナンス時は 503 + Retry-After を返す
- セキュリティ上の理由で「情報を隠す」設計も必要
WebAPIのエラー設計は、クライアント体験とセキュリティを両立させる大事な要素です。
おわりっ！
Discussion