Help users to…

Recover from errors

Also known as: Error messages

Note: The guidelines below don’t apply to inline error messages in form fields (for example, “Please enter a valid Social Security number.”). Inline form field error messages will be handled in a separate error guide.

Structure

Every error message will have up to 3 parts:

1.Title

• Bold title giving the user a quick idea of what’s wrong (or, for informational alerts, the key message the user needs to know).

2. Description

• Apology (if the error is coming from a problem on our end).
• Succinct description of the issue, cause, and any relevant details.
• Call to action telling the user what to do next (if applicable).
• Next-step call to action telling the user what to do if the first call to action fails to resolve the issue (if applicable).

3. Button or Link

• Actionable next-step for user (if applicable).

Content within the message - General

To create an effective error message, ask yourself these 4 questions:

1. What’s the error/issue?

The answer will inform the details of the issue and cause.

2. What’s the source of the error/issue?

The answer will determine how the error/issue needs to be framed, and whether an apology is needed.

Consider if the issue is caused by:

A. The user’s action

B. An authorization issue. If so, consider whether the issue is due to:

• VA.gov’s inability to find user’s records in our system
• The user’s records showing user can’t use benefit/service (ie, user isn’t a VA patient, user isn’t enrolled in benefit/service, user isn’t eligible for benefit/service)
• Something else

C. A system or network access issue. If so, consider whether the issue:

• Affects the entire site or just one page/application/component/user task
• Is scheduled/expected or unexpected
• Is the result of an issue of VA.gov, a separate site/app (such as DS Logon), or Internet network connection

3. What does the user need to know to resolve the error/issue?

The answer will inform the call to action telling the user what to do next, as well as any relevant details.

For an error caused by or due to:

• User action. Offer the user clear guidance on how to resolve the error (ie, “Please make sure your file is a .pdf format”).
• Authorization issue. If the issue is due to VA.gov inability to find user’s records in our system, direct the user to try again or call the VA.gov help desk if they think their records should be available.
• User’s records showing the user can’t use benefit/service. Offer a path forward:
  • User not eligible for benefit: Direct to relevant eligibility information
  • User not enrolled in benefit: Direct to relevant eligibility information and application page.
  • User not a VA patient: Direct to facility locator to find contact information to call their VA facility.
• System or network access issue. The error message should include timing for when the user should try again. This can be specific timing (eg, in an hour, tomorrow, etc.) if an estimate is available or more general timing (eg, soon, later) if an estimate isn’t available.

4. If the resolution fails, what’s the next step?

The answer will inform whether or not to include a “next-step call to action” to help guide the user further should the first call to action fail to resolve the issue. This may be language directing the user to call the VA.gov help desk or other VA resources, and will be determined on an issue-by-issue basis. See Next-step calls to action below for more information and guidance.

Content within the message - Task completion

Below are examples of each type of Alert style for task completion.

Success alerts

Create a brief title documenting the task that was successfully completed, followed by a brief description of the success.

Saved

Error alerts

Include exactly what failed in the title, followed by a brief apology, reiteration of the failure reframed in the VA.gov perspective, and prompt to try again.

Your form didn’t save

Consider whether there is additional information, including a time estimate for resolution and/or a call to action button, that should be included.

Please save this application and try again

Informational messages and warnings

To create an effective informational message or warning, ask yourself these 2 questions:

1. What’s the key information the user needs to know?

This information should be presented as succinctly as possible in the title and then reiterated in the description with any additional relevant details.

Informational example

Warning example

2. Does the user need to take action, or do we want the user to take action?

When action is required, frame required information as a need.

We need your help to finish reviewing your claim

When we want to prompt the user to take action, frame the prompt as a question to engage the user.

Want to make your VA.gov account more secure?

Messages dictionary

The messages dictionary holds the title, content, component, and state for each scenario of message on the site.

View the messages dictionary

Style and tone

Clear and direct

Tell the user what’s happened/happening, how it will impact them, and how they can resolve it.

Humble, helpful, and non-alarming

Framed to highlight VA.gov ownership/shared ownership of the error

Did the user’s action cause the error?

If yes: Avoid language that feels alarming or blame-oriented and re-frame error as being a shared one, while guiding user to correct the error.

If no: Accept responsibility for the error and offer user brief, but clear, details and guidance to resolution.

Conversational and plain language

First person/second person with a personal/helpful tone. Example:

Plain, simple words (ie, avoid jargon and multisyllabic words wherever possible). Examples:

When the instructions are conditional, lead with the conditional phrase to make it clear who the instructions are for. Examples:

Additional guidance

Error state and message intent

Focusing in on the intent of the error message can help to further flesh out the nuances of tone and description content.

Messaging categories

The Messaging Dictionary can help offer specific messages to use and/or examples to inform new message creation. We’ll continue to expand the dictionary, so check back often for new messages.

Next-step calls to action

Some errors may not be resolved based on initial instructions to user (ie, “Try again later”). In these cases, a next-step call to action (ie, “Call the VA.gov help desk”) may be necessary. This will be decided on a case-by-case basis, but below are some initial guidelines for determining the appropriate next-step call to action.