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 numerous error messages throughout my career, and I've come to realize that writing good error messages is an art that requires careful consideration. Error messages are often the first point of contact between the user and the system when something goes wrong, and they can significantly impact the user experience.

User-Facing Errors

User-facing errors are those that are displayed directly to the user. These errors should be clear, concise, and provide enough information for the user to understand what went wrong and how to recover. A good user-facing error message should include the following elements:

  • A clear description of the error
  • A suggested course of action to resolve the issue
  • Any relevant details, such as error codes or affected systems

For example, consider the following bad error message:

Error 500: Internal Server Error

This error message provides little to no information about what went wrong or how to recover. A better example would be:

Failed to load data: Unable to connect to the database. Please try again later or contact support if the issue persists.

This error message provides a clear description of the error, suggests a course of action, and provides additional context.

Developer-Facing Errors

Developer-facing errors, on the other hand, are those that are intended for the development team. These errors should provide detailed information about the error, including any relevant technical details, such as stack traces or error codes. A good developer-facing error message should include the following elements:

  • A detailed description of the error
  • Relevant technical details, such as stack traces or error codes
  • Suggestions for debugging or resolving the issue

For example, consider the following bad error message:

Error: Something went wrong

This error message provides no useful information for the developer to diagnose or resolve the issue. A better example would be:

Error: Unable to connect to database (error code: 1045). Stack trace: ...

This error message provides a detailed description of the error, includes relevant technical details, and provides a starting point for debugging.

Log Messages

Log messages are used to record events or errors within the system. These messages should be clear, concise, and provide enough information for the developer to understand what happened. A good log message should include the following elements:

  • A timestamp of when the event occurred
  • A clear description of the event or error
  • Any relevant details, such as user IDs or affected systems

For example, consider the following bad log message:

Error occurred

This log message provides no useful information about what happened or when. A better example would be:

2023-02-15 14:30:00: Error connecting to database (error code: 1045) for user ID 123

This log message provides a timestamp, a clear description of the error, and relevant details about the affected user.

API Error Responses

API error responses are used to communicate errors to clients or other systems. These responses should follow standard conventions, such as HTTP status codes, and provide enough information for the client to understand what went wrong. A good API error response should include the following elements:

  • A standard HTTP status code (e.g., 400, 500)
  • A clear description of the error
  • Any relevant details, such as error codes or affected systems

For example, consider the following bad API error response:

{
  "error": "Something went wrong"
}

This error response provides no useful information about what went wrong or how to recover. A better example would be:

{
  "status": 400,
  "error": "Invalid request data",
  "details": "Missing required field: username"
}

This error response follows standard conventions, provides a clear description of the error, and includes relevant details about the affected field.

Practical Takeaways

When writing error messages, consider the following best practices:

  • Be clear and concise
  • Provide enough information for the user or developer to understand what went wrong
  • Include relevant details, such as error codes or affected systems
  • Follow standard conventions, such as HTTP status codes for API error responses
  • Test your error messages to ensure they are effective and easy to understand By following these best practices, you can write effective error messages that improve the user experience and simplify debugging for developers.