この記事の対象読者

画面のエラー表示を実装する人
技術的なエラーをユーザー向け文言に直したい人
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を添える。

この分け方だけでも、「失敗しました」で止まる画面から一歩進めます。

参考