MEHDI.
RETURN_TO_INDEX

The Art of Writing Good Error Messages

4 min read
#Backend#Software Engineering#UX

Introduction

As a developer, I've encountered my fair share of error messages, some helpful and others frustratingly vague. Error messages are a crucial part of the user experience and the development process. They can make the difference between a smooth, efficient workflow and a tedious, time-consuming one. In this article, I will discuss the art of writing good error messages, covering user-facing errors, developer-facing errors, log messages, and API error responses.

User-Facing Errors

User-facing errors occur when something goes wrong while a user is interacting with an application. A good user-facing error message should be clear, concise, and helpful. It should inform the user what went wrong and provide guidance on how to fix the issue.

For example, consider a login form that displays the following error message when the username or password is incorrect:

Invalid username or password

This error message is not very helpful. A better version would be:

Invalid username or password. Please check your credentials and try again. If you're still having trouble, click the 'Forgot password' link to reset your password.

This revised error message provides more context and offers suggestions for resolving the issue.

Developer-Facing Errors

Developer-facing errors occur during the development process, often when debugging or testing code. These error messages should be detailed and informative, providing enough information for the developer to diagnose and fix the problem.

For instance, consider a Python script that throws the following error:

Error on line 10

This error message is not very informative. A better version would be:

TypeError on line 10: cannot concatenate 'str' and 'int' objects

This revised error message provides more context, including the type of error and the line number where it occurred.

Log Messages

Log messages are used to record events that occur during the execution of an application. They can be useful for debugging purposes, but they should not be too verbose or cluttered with unnecessary information. A good log message should be concise and informative, providing enough context to help diagnose issues.

For example, consider a log message that reads:

Something went wrong

This log message is not very helpful. A better version would be:

Error processing request: unable to connect to database (timeout after 5 seconds)

This revised log message provides more context, including the type of error and the reason for the failure.

API Error Responses

API error responses occur when an API request fails or returns an error. These responses should be standardized and follow established conventions, such as the HTTP status code conventions. A good API error response should include a clear and concise error message, as well as any relevant details or suggestions for resolving the issue.

For instance, consider an API that returns the following error response:

HTTP/1.1 500 Internal Server Error

This error response is not very informative. A better version would be:

HTTP/1.1 404 Not Found
{
  'error': 'Resource not found',
  'message': 'The requested resource could not be found',
  'status_code': 404
}

This revised error response provides more context, including a clear error message and a relevant HTTP status code.

Practical Takeaways

When writing error messages, keep the following best practices in mind:

  • Be clear and concise
  • Provide relevant context and details
  • Offer suggestions for resolving the issue
  • Follow established conventions and standards
  • Test and refine your error messages to ensure they are effective and helpful By following these guidelines, you can write effective error messages that improve the user experience and facilitate the development process.