実用的なエラー メッセージを作成する
コレクションでコンテンツを整理
必要に応じて、コンテンツの保存と分類を行います。
このページでは、ユーザーが目標を達成できるように、問題の解決方法をユーザーに伝えるための、実用的なエラー メッセージを作成するためのベスト プラクティスについて説明します。
ユーザーが Google Chat 用アプリを操作しているときに、エラー メッセージが表示されると、そのエラーが解決できない場合はストレスを感じることがあります。たとえば、エラー メッセージ An error occurred は、何が問題だったのか、ユーザーが問題を解決するにはどうすればよいのか、ユーザーがサポートを受けるにはどうすればよいのかが説明されていないため、役に立ちません。このページでは、ユーザーにとって役立つエラー メッセージを構成する方法について、実行可能な例と実行不可能な例を示しながら説明します。
エラー メッセージの構造
対応可能なエラー メッセージの構造は次のとおりです。
- 何が問題だったか。Chat アプリがリクエストを完了できない理由を説明すると、ユーザーが問題を解決するのに役立ちます。エラーが発生した理由を説明することで、信頼を築くことができます。
- ユーザーが目標を達成するための手順。何が間違っていたかを言うだけでは十分ではありません。エラーを回避して目標を達成する方法をユーザーに伝えます。
- サポートの利用方法。それでも問題が解決しない場合は、サポートを受ける方法をお客様に伝えます。
/help コマンドや、Chat 用アプリのドキュメントへのリンクを指定できます。
この例では、ユーザーが Chat 用アプリが想定していない形式で日付を入力しています。November 19, 2021 と記述しましたが、Chat アプリでは 2021-11-19 が想定されています。
Chat 用アプリが返すエラー メッセージの、対応可能なバージョンと対応不可能なバージョンを以下に示します。
対処可能なエラー
ユーザーが Chat 用アプリに別のユーザーとの会議のスケジュール設定を依頼します。Chat 用アプリから、適切なエラー メッセージが返されます。
I don't recognize the date format you entered. Write dates as `yyyy-mm-dd`; for example, `2000-01-31`. For help, type `/help`.
このエラー メッセージは、次の理由で対応可能です。
- 何が問題だったかを表示します。Chat 用アプリが日付形式を認識しない。
- ユーザーに想定される日付形式を伝え、入力する内容を理解するのに役立つ日付の例を示すことで、エラーを修正する方法を説明します。
/help スラッシュ コマンドで詳細なヘルプを提供します。それでも解決しない場合は、詳細を確認する方法がわかります。
対応できないエラー
ユーザーが Chat 用アプリに別のユーザーとの会議のスケジュール設定を依頼します。Chat 用アプリから、役に立たない、対応できないエラー メッセージが返されます。
Enter the correct date format.
このエラー メッセージは、次の理由で対応できません。
- 会議のスケジュールを設定したかどうかは表示されません。ユーザーは会議のスケジュール変更をためらったり、会議がスケジュールされていると思い込んだりする可能性があります。
- 日付の形式を指定する方法がユーザーに伝わっていない。ユーザーが日付の形式を理解していることを前提とするのではなく、日付の形式
yyyy-mm-dd が必要であることを明記する必要があります。
- 他にサポートが必要かどうかを尋ねなかった。ユーザーが先に進めなくなって、どうすればよいかわからなくなると、Chat 用アプリへのメッセージ送信を停止する可能性があります。
試してみる
対処可能なエラーの書き方を理解したところで、次のシナリオで対処可能なエラーを特定してください。
ユーザーがキーワード schedule を使用して Chat 用アプリにメッセージを送信すると、Chat 用アプリがカレンダーの予定を作成します。カレンダーの予定を作成するには、Chat 用アプリでユーザー認証が必要です。ユーザーが認証されていない場合、Chat 用アプリはエラー メッセージを返します。
どのエラー メッセージが実用的ですか？
会議のスケジュールを設定するには、/signin と入力してログインする必要があります。詳しくは、/help と入力してください。
このエラー メッセージは、次のように表示されるため、対応可能です。
- 何が問題だったか。Chat 用アプリには認証が必要です。
- 手順。「
/signin」と入力して認証します。
- サポートの利用方法。詳細な情報を必要とする場合は、
/help と入力します。
認証する必要があります。
このエラー メッセージには認証方法が記載されていないため、対応できません。
ログインします。
このエラー メッセージは、ログイン方法が記載されておらず、ユーザーがログアウトしていることを明確に示していないため、対処できません。また、ユーザーがログアウトしていることを明確に示していないため、混乱を招く可能性があります。
会議のスケジュールを設定できません。
このエラー メッセージは、会議をスケジュールできない理由や、ユーザーがどのように対処すればよいかが示されていないため、ユーザーが対応できません。ヘルプは提供されません。
特に記載のない限り、このページのコンテンツはクリエイティブ・コモンズの表示 4.0 ライセンスにより使用許諾されます。コードサンプルは Apache 2.0 ライセンスにより使用許諾されます。詳しくは、Google Developers サイトのポリシーをご覧ください。Java は Oracle および関連会社の登録商標です。
最終更新日 2025-08-29 UTC。
[null,null,["最終更新日 2025-08-29 UTC。"],[[["\u003cp\u003eGoogle Chat app error messages should be actionable, guiding users on how to resolve issues and proceed.\u003c/p\u003e\n"],["\u003cp\u003eActionable error messages clearly explain the problem, provide steps for fixing it, and offer additional help resources.\u003c/p\u003e\n"],["\u003cp\u003eInactionable error messages are vague, lack guidance, and can lead to user frustration and abandonment.\u003c/p\u003e\n"],["\u003cp\u003eUse the actionable error message structure: state the problem, guide the user on fixing it, and offer further help (e.g., \u003ccode\u003e/help\u003c/code\u003e command).\u003c/p\u003e\n"],["\u003cp\u003eWhen writing error messages, assume users need clear instructions and avoid ambiguity.\u003c/p\u003e\n"]]],["Actionable error messages in Google Chat apps should specify what went wrong, how to fix it, and how to get further assistance. For example, an actionable message for an incorrect date format would state that the format is unrecognized, specify the required format (yyyy-mm-dd), and provide a /help command. In contrast, inactionable errors are vague, omit how to correct the issue, and offer no additional support. A sign-in error should also include clear instructions, and help commands.\n"],null,["# Write actionable error messages\n\nThis page describes best practices to write actionable error messages that tell\nthe user how to fix the issue so that they can complete their goal.\n\nWhen a user is interacting with a Google Chat app, encountering\nerror messages can be a frustrating experience when the error isn't actionable.\nFor example, the error message, `An error occurred`, isn't useful because the\nmessage doesn't explain what went wrong, how the user can fix the issue, or how\nthe user can get help. This page describes how to structure error messages so\nthat they're useful to users by showing actionable and inactionable examples.\n\nError message structure\n-----------------------\n\nAn actionable error message has the following structure:\n\n- **What went wrong.** Saying why the Chat app can't complete a request helps the user resolve the issue. Explaining why an error occurred builds trust.\n- **How the user can proceed toward their goal.** It's never enough to just say what went wrong. Tell users how they can move past the error and complete their goal.\n- **How to get help.** If the user is still stuck, tell them how they can get more help. This could be a `/help` command or a link to documentation for your Chat app.\n\nExample error message: incorrect date format\n--------------------------------------------\n\nIn this example, the user entered a date in a format that\nthe Chat app didn't expect. They wrote\n`November 19, 2021`, but the Chat app expects\n`2021-11-19`.\n\nHere's an actionable and an inactionable version of the error message that the\nChat app responds with:\n\n#### Actionable error\n\nA user asks the Chat app to schedule a meeting with\nanother person. The Chat app responds with a good,\nactionable error message:\n\n``I don't recognize the date format you entered. Write dates as `yyyy-mm-dd`; for example, `2000-01-31`. For help, type `/help`.``\n\nThis error message is actionable for the following reasons:\n\n- Says what went wrong. The Chat app doesn't recognize the date format.\n- Explains how to fix the error by telling the user the expected date format and gives an example date that helps people understand what to write.\n- Offers more help with a `/help` slash command. If users are still stuck, they know how to learn more.\n\n#### Inactionable error\n\nA user asks the Chat app to schedule a meeting with\nanother person. The Chat app responds with an\nunhelpful, inactionable error message:\n\n`Enter the correct date format.`\n\nThis error message is inactionable for the following reasons:\n\n- Doesn't say whether it scheduled the meeting. The user might be hesitant to reschedule the meeting, or they might assume that the meeting was scheduled.\n- Doesn't tell the user how to format the date. Instead of assuming that users know how to format the date, it should say that it's expecting the date format `yyyy-mm-dd`.\n- Doesn't offer more help. When users are stuck and don't know how to proceed, they might stop messaging the Chat app.\n\nTry it out\n----------\n\nNow that you know how to write actionable errors, can you identify in the\nfollowing scenario which of these errors is actionable:\n\nA Chat app creates calendar events when users message\nthe Chat app with the keyword `schedule`. To\ncreate a calendar event, the Chat app requires user\nauthentication. If a user hasn't been authenticated, then the\nChat app responds with an error message. \nWhich error message is actionable? \nBefore I can schedule the meeting, you must sign in by typing `/signin`. To learn more, type `/help`. \nThis error message is actionable because it says the following:\n\n- What went wrong. The Chat app requires authentication.\n- How to proceed. Type `/signin` to authenticate.\n- How to get help. If the user wants more information, they can type `/help`. \nYou must authenticate. \nThis error message is inactionable because it doesn't say how to authenticate. \nSign in. \nThis error message is inactionable because it doesn't say how to sign in, and it implies that the user is signed out instead of clearly saying so, which is confusing. \nCan't schedule meeting. \nThis error message is inactionable because it doesn't tell the user why the meeting can't be scheduled or how the user can proceed. No help is provided."]]
