この記事の対象読者
- 画面のエラー表示を実装する人
- 技術的なエラーをユーザー向け文言に直したい人
- CSや問い合わせ対応を意識して画面を作りたい人
本題に入る前に
フロントエンドを実装している人は耳にタコかもしれませんが、画面に「エラーが発生しました」とだけ出ても、使っている人は次に何をすればよいか分かりません。
エラーが発生しました。
問い合わせ対応をしていると、「この文言だとユーザーが困るよね」と感じる場面があります。実際には入力を直せばよいだけなのに、全部「失敗しました」と出ていたら、問い合わせるしかなくなります。
エラー文言は、原因を全部説明するためのものではありません。まずは、ユーザーが次に取れる行動を伝えるためのものです。
ユーザー向け文言とログ向け情報を分ける
エラーには、画面に出したい情報と、ログに残したい情報があります。
たとえば、画面にはこう出します。
予約の保存に失敗しました。
時間をおいて再度お試しください。
解決しない場合は、サポートにお問い合わせください。
ログにはこう残します。
{
"operation": "reservation_create",
"status": "failure",
"errorCode": "EXTERNAL_API_TIMEOUT",
"requestId": "req_001"
}
内部のエラーコードやスタックトレースをそのまま画面に出す必要はありません。
エラーコードから文言へ変換する
TypeScriptで小さく書くなら、エラーコードと表示文言を対応させます。
type AppErrorCode =
| "VALIDATION_ERROR"
| "AUTH_REQUIRED"
| "EXTERNAL_API_TIMEOUT"
| "UNKNOWN_ERROR";
const userMessages: Record<AppErrorCode, string> = {
VALIDATION_ERROR: "入力内容を確認してください。",
AUTH_REQUIRED: "ログインが必要です。もう一度ログインしてください。",
EXTERNAL_API_TIMEOUT:
"外部サービスとの通信に時間がかかっています。時間をおいて再度お試しください。",
UNKNOWN_ERROR:
"処理に失敗しました。時間をおいて再度お試しください。",
};
function toUserMessage(errorCode: AppErrorCode) {
return userMessages[errorCode] ?? userMessages.UNKNOWN_ERROR;
}
画面側は、この関数を通して表示します。
function ErrorMessage({ errorCode }: { errorCode: AppErrorCode }) {
return <p role="alert">{toUserMessage(errorCode)}</p>;
}
こうしておくと、画面ごとに文言がばらつきにくくなります。
問い合わせにつながる情報も出す
問い合わせ時に役立つ情報は、画面にも少し出しておくと親切です。
予約の保存に失敗しました。
時間をおいて再度お試しください。
お問い合わせ時は、次のIDをお伝えください。
requestId: req_001
requestIdがあると、サポートやエンジニアがログを探しやすくなります。
ただし、ユーザーIDや内部IDをどこまで出すかはサービスの方針に合わせます。画面に出してよい情報と、ログだけに残す情報は分けて考えます。
文言を考えるときの型
エラー文言は、次の3つで考えると作りやすいです。
| 要素 | 例 |
|---|---|
| 何が起きたか | 予約の保存に失敗しました |
| 次に何をするか | 時間をおいて再度お試しください |
| 問い合わせるなら何を伝えるか | requestIdを添えてください |
「申し訳ありません」だけでは行動につながりません。「エラーです」だけでも不親切です。
使う人が次に動ける文言にすると、問い合わせも調査も少し楽になります。
まとめ
エラー文言は、技術的な原因をそのまま出す場所ではありません。
ユーザーには次の行動を伝える。ログには調査に必要な情報を残す。問い合わせ時に必要ならrequestIdを添える。
この分け方だけでも、「失敗しました」で止まる画面から一歩進めます。