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, ranging from cryptic and confusing to clear and informative. Writing good error messages is an art that requires a deep understanding of the user's needs and the context in which the error occurs. In this article, I'll discuss the importance of well-crafted error messages and provide guidelines for writing effective user-facing errors, developer-facing errors, log messages, and API error responses.

User-Facing Errors

User-facing errors are those that are displayed directly to the end-user. The primary goal of these errors is to inform the user of what went wrong and provide guidance on how to recover. A good user-facing error message should be clear, concise, and free of technical jargon.

For example, consider the following bad error message:

Error 500: Internal Server Error

This message tells the user that something went wrong, but it doesn't provide any useful information about what happened or how to fix it.

In contrast, a good error message might look like this:

Sorry, we're experiencing technical difficulties. Please try again later or contact our support team for assistance.

This message is more informative and provides the user with a clear course of action.

Developer-Facing Errors

Developer-facing errors are those that are intended for developers, either during development or when debugging production issues. These errors should provide detailed information about what went wrong and why. A good developer-facing error message should include the following:

  • A clear description of the error
  • Relevant context, such as variable values or function calls
  • Suggestions for how to fix the error

For example, consider the following bad error message:

Error: unable to connect to database

This message doesn't provide any useful information about what might be causing the error.

In contrast, a good error message might look like this:

Error: unable to connect to database. Check that the database server is running and that the connection string is correct. 
Database connection string: postgres://user:password@host:port/dbname

This message provides more detailed information about the error and suggests potential solutions.

Log Messages

Log messages are used to record events that occur during the execution of a program. They can be useful for debugging purposes, but they should be written with the assumption that they will be read by a developer who is familiar with the code. A good log message should include the following:

  • A clear description of the event
  • Relevant context, such as variable values or function calls
  • Any error messages or exceptions that occurred

For example, consider the following log message:

2023-02-20 14:30:00 ERROR - unable to connect to database

This message is brief and to the point, but it doesn't provide any useful information about what might be causing the error.

In contrast, a good log message might look like this:

2023-02-20 14:30:00 ERROR - unable to connect to database. 
Database connection string: postgres://user:password@host:port/dbname. 
Exception: java.sql.SQLException: Connection refused

This message provides more detailed information about the error and includes the exception message.

API Error Responses

API error responses are used to communicate errors to clients that are consuming an API. They should be written in a standard format, such as JSON, and should include the following:

  • A clear description of the error
  • A unique error code
  • Any additional information that might be useful to the client

For example, consider the following bad API error response:

HTTP/1.1 500 Internal Server Error

This response doesn't provide any useful information about what went wrong.

In contrast, a good API error response might look like this:

HTTP/1.1 400 Bad Request
Content-Type: application/json

{
  "error": {
    "code": 1001,
    "message": "Invalid request parameters",
    "details": "The 'name' parameter is required."
  }
}

This response provides more detailed information about the error and includes a unique error code.

Practical Takeaways

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

  • Be clear and concise
  • Provide relevant context
  • Suggest potential solutions
  • Use a standard format for API error responses
  • Test your error messages to ensure they are effective By following these guidelines, you can write error messages that are informative, helpful, and improve the overall user experience.