The Art of the Good Error Message

You've seen them. “Something went wrong.” “Invalid input.” “Error 503.” These messages are technically true but completely useless. The person reading them has no idea what to do next. A good error message is different. It tells you what happened, why it matters, and what to try.

The Three Parts of a Good Error

Every useful error message answers three questions: what went wrong, why it happened, and the user can do about it.

Bad: “Authentication failed.” Good: “Your password was incorrect. You have two attempts remaining. Try again or click 'Forgot password.'” The first blames the user. The second helps the user.

Be Specific

Vague errors are worse than no errors. “File not found” is useless. Which file? Where did you look? What were you trying to do? “The configuration file 'settings.json' was not found in /app/config. Using default values.” That tells you exactly what happened and that the system is recovering.

Don't Blame the User

Phrasing matters. “Invalid input” sounds like the user is wrong. “We didn't recognize that email address. Please check spelling or use the one you signed up with.” Same information. Less aggressive. The user isn't the enemy.

Include a Next Step

Every error should point somewhere. A button. A link. An instruction. Even *contact support* is better than nothing. “Try again in a few minutes.” “Check your internet connection.” “Restart the app.” Tell them what to do, not just what's wrong.

A Real Example

Here's a bad error from an API.

{ "error": "Bad request" }

Here's the same error done well.

{
  "error": "Invalid 'email' field",
  "detail": "The value 'notanemail' is not a valid email address. Expected format: [email protected].",
  "help": "See https://api.example.com/docs#email-format"
}

The first makes you guess. The second tells you the field, the problem, the expected format, and where to look for more info.

Writing good error messages takes practice. But the rule is simple: imagine you're the person seeing the error for the first time. Write what you'd want to read.