デバッグ・エラーメッセージの文字数設計ガイド
エラーメッセージは、ユーザーと開発者の双方にとって重要な情報伝達手段です。ユーザー向けのエラーメッセージは簡潔で行動を促す内容が求められ、開発者向けのデバッグ情報は問題の特定に十分な詳細が必要です。文字数が不適切なエラーメッセージは、ユーザーの離脱や障害対応の遅延を招きます。本記事では、エラーメッセージの場面別の推奨文字数と、UX と運用効率を両立する設計テクニックを解説します。
ユーザー向けエラーメッセージの文字数
ユーザーに表示するエラーメッセージは、問題の内容と解決方法を簡潔に伝える必要があります。
| エラーの種類 | 推奨文字数 | 含めるべき情報 | 例 |
|---|---|---|---|
| 入力バリデーション | 20〜60 文字 | 何が間違いか + 正しい形式 | 「メールアドレスの形式が正しくありません。例: user@example.com」 |
| 認証エラー | 30〜80 文字 | 原因 + 対処法 | 「パスワードが正しくありません。お忘れの場合はリセットしてください。」 |
| サーバーエラー | 30〜60 文字 | 状況 + 次のアクション | 「一時的な問題が発生しました。しばらくしてから再度お試しください。」 |
| 権限エラー | 30〜80 文字 | 原因 + 対処法 | 「この操作を行う権限がありません。管理者にお問い合わせください。」 |
| ネットワークエラー | 30〜60 文字 | 状況 + 対処法 | 「インターネット接続を確認してください。接続後に再度お試しください。」 |
| 404 エラー | 40〜100 文字 | 状況 + 代替案 | 「お探しのページが見つかりません。URL を確認するか、トップページからお探しください。」 |
ユーザー向けエラーメッセージの鉄則は「何が起きたか」「なぜ起きたか」「どうすればよいか」の 3 要素を含めることです。ただし、セキュリティ上の理由から、認証エラーでは「メールアドレスが存在しません」のような詳細な情報は避け、「メールアドレスまたはパスワードが正しくありません」のように曖昧にすることが推奨されます。
開発者向けデバッグメッセージの文字数
開発者向けのデバッグメッセージは、問題の原因特定に必要な情報を網羅する必要があります。
- 例外メッセージ (30〜150 文字): 例外の種類と発生箇所を特定できる情報を含めます。「NullPointerException: user.getEmail() returned null at UserService.java:42」
- スタックトレース (500〜3,000 文字): 呼び出し階層を示すスタックトレースは、先頭 5〜10 フレームが最も重要です。フレームワーク内部のフレームは省略可能
- コンテキスト情報 (50〜300 文字): リクエスト ID、ユーザー ID、タイムスタンプ、入力パラメータなど、再現に必要な情報を付加します
- デバッグログ (20〜100 文字/行): 処理の各ステップで出力するデバッグログは、1 行あたり 20〜100 文字が適切です
開発者向けメッセージで最も重要なのは「再現可能性」です。メッセージを読んだ別の開発者が、同じ問題を再現できるだけの情報が含まれているかを基準に文字数を決定します。
HTTP ステータスメッセージの文字数
API のレスポンスに含めるエラーメッセージは、クライアントアプリケーションが適切にハンドリングできる構造が求められます。
| HTTP ステータス | メッセージ文字数 | 詳細フィールド文字数 | 用途 |
|---|---|---|---|
| 400 Bad Request | 20〜60 文字 | 50〜200 文字 | リクエストの形式エラー |
| 401 Unauthorized | 20〜40 文字 | 30〜100 文字 | 認証が必要 |
| 403 Forbidden | 20〜50 文字 | 30〜100 文字 | アクセス権限なし |
| 404 Not Found | 20〜40 文字 | 30〜80 文字 | リソースが存在しない |
| 429 Too Many Requests | 20〜50 文字 | 30〜100 文字 | レート制限超過 |
| 500 Internal Server Error | 20〜40 文字 | 50〜200 文字 | サーバー内部エラー |
API のエラーレスポンスは JSON 形式で返すのが一般的です。message フィールドに人間が読めるメッセージ、code フィールドにマシンリーダブルなエラーコード、details フィールドに詳細情報を含める構造が推奨されます。
エラーメッセージの多言語対応
グローバルなサービスでは、エラーメッセージの多言語対応が必要です。言語によって文字数が大きく変わるため、UI 設計時に余裕を持たせる必要があります。
- 日本語 → 英語: 英語は日本語の 1.5〜2 倍の文字数になることが多い。日本語 40 文字のメッセージが英語では 60〜80 文字になる
- 日本語 → ドイツ語: ドイツ語は英語よりもさらに長くなる傾向があり、日本語の 2〜2.5 倍になることも
- UI の余裕: エラーメッセージの表示領域は、最も長い言語に合わせて設計します。日本語基準で設計すると、他言語で文字が切れる問題が発生します
- i18n キーの命名: エラーメッセージの i18n キーは、エラーの種類を反映した命名にします。例: `error.auth.invalid_credentials`、`error.validation.email_format`
エラーメッセージのアンチパターン
避けるべきエラーメッセージのパターンを紹介します。これらは文字数の問題だけでなく、UX やセキュリティにも悪影響を及ぼします。
- 「エラーが発生しました」(11 文字): 情報量ゼロのメッセージ。何が起きたか、どうすればよいかが一切わからない
- 技術用語の羅列: 「SQLException: ORA-00942: table or view does not exist」をそのままユーザーに表示するのは論外。内部エラーはログに記録し、ユーザーには平易な言葉で伝える
- 責任転嫁: 「お客様の操作に問題があります」のような表現は、ユーザーの不満を増大させる。「入力内容をご確認ください」のように中立的な表現を使う
- 過度に長い説明: 200 文字を超えるエラーメッセージは、ユーザーが読まない可能性が高い。詳細は「詳しく見る」リンクで別ページに誘導する
エラーメッセージの UX 設計
エラーメッセージは単なるテキストではなく、UX の一部として設計する必要があります。
- インラインバリデーション: フォーム入力時にリアルタイムでエラーを表示する場合、メッセージは 20〜40 文字に抑え、入力フィールドの直下に表示します
- トースト通知: 画面上部や下部に一時的に表示するトースト通知は、30〜60 文字が適切。3〜5 秒で自動的に消えるため、瞬時に読める長さが必要です
- モーダルダイアログ: 重要なエラーをモーダルで表示する場合、タイトル 10〜20 文字 + 本文 50〜150 文字 + アクションボタン 5〜15 文字の構成が効果的です
- 色とアイコン: エラーは赤色 + 警告アイコン、警告は黄色 + 注意アイコン、情報は青色 + 情報アイコンで視覚的に区別します。色だけに頼らず、テキストでも状態を伝えることがアクセシビリティの観点から重要です
まとめ
エラーメッセージの文字数は、ユーザー向けが 20〜100 文字、開発者向けが 30〜3,000 文字、API レスポンスが 20〜200 文字が目安です。「何が起きたか」「どうすればよいか」を簡潔に伝えることが、優れたエラーメッセージの条件です。エラーメッセージの文字数確認には、文字数カウントスをぜひご活用ください。