---
title: "Error messages"
slug: "error-messages"
description: "Learn to craft clear, concise, and actionable error messages that enhance user experience with empathy, consistency, and accessibility guidelines."
updated: 2026-07-27T06:48:12Z
published: 2026-07-27T06:48:12Z
canonical: "docs.document360.com/error-messages"
---

> ## Documentation Index
> Fetch the complete documentation index at: https://docs.document360.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Error messages

Well-crafted error messages help users understand what went wrong and how to fix it — reducing frustration and support requests. This guide sets standards for writing clear, consistent, and empathetic error messages across the UI.

## Core Principles

| Principle | What it means |
| --- | --- |
| **Clarity** | Use simple, everyday language. Avoid jargon and vague descriptions. |
| **Actionability** | Tell the user exactly what to do next. If no action is needed, say so. |
| **Empathy** | Never blame the user. Use supportive, neutral phrasing. |
| **Consistency** | Use the same tone, structure, and terminology across all messages (e.g., don't mix "server error" and "system error" for the same issue). |
| **Brevity** | Keep it short — enough context to be useful, no more. |
| **Accessibility** | Follow WCAG guidelines so messages are understandable to users of all abilities. |

## Anatomy of an Error Message

Every error message should answer up to three questions:

1. **What happened?** State the problem plainly.
2. **Why did it happen?** *(optional)* Add a brief reason if it helps the user understand.
3. **What should the user do next?** Give a specific action or point to further help.

**Structure:**

| Component | Example |
| --- | --- |
| Header | "Unable to Process Request" |
| Description | "We encountered an issue while processing your request. Please try again." |
| Action/Help | "If the problem persists, contact support at support@document360.com." |

## Writing Guidelines

| Guideline | ✅ Do | ❌ Don't |
| --- | --- | --- |
| Use plain language | "The file size exceeds the allowed limit." | "File upload failed due to size constraints." |
| Be specific | "Invalid email address. Please enter a valid format (e.g., name@domain.com)." | "Input error." |
| Provide a solution | "The username is already taken. Try a different username." | "This username is not available." |
| Avoid technical jargon | "We couldn't connect to the server. Check your internet connection and try again." | "Server 503 error detected." |
| Use polite, positive language | "Something went wrong. Please try again in a few minutes." | "Error! Try again." |
| Align with context | "We couldn't save that. Please retry." | "Save error! Action blocked!" |
| Use active voice | "We couldn't find the requested article." | "The requested article was not found." |
| Avoid negative words | "We couldn't complete your request." | "Failed to process your request." |

**Error codes:** Include them only for complex or technical errors where they aid troubleshooting.

> Example: "The request couldn't be processed (Error Code: 403). Contact support for assistance."

## Common Error Scenarios

| Scenario | Error message |
| --- | --- |
| Invalid input | "Invalid password. Password must be at least 8 characters and include a number." |
| Missing required field | "Email address is required. Please enter your email to proceed." |
| Server timeout | "We're having trouble connecting to the server. Please try again later." |
| File upload error | "File upload failed. Ensure the file is under 5 MB and in a supported format." |
| Access denied | "You don't have permission to view this page. Contact your administrator." |
| Payment failure | "Payment couldn't be processed. Check your card details or try a different method." |
| Duplicate entry | "This category name already exists. Please choose a different name." |
| Session expired | "Your session has expired. Please log in again to continue." |

## Pre-Publish Checklist

- Is the message clear and concise?
- Does it explain what went wrong?
- Does it offer an actionable next step?
- Is it free of technical jargon?
- Is the tone polite and professional?
- Is it consistent with other error messages in the product?

## Maintenance

Review all error messages periodically as product features evolve, and update them promptly to prevent outdated or confusing guidance.