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 have been helpful and informative, while others have been cryptic and frustrating. In this article, I'll discuss the importance of writing good error messages and provide examples of how to do it effectively.

User-Facing Errors

User-facing errors are those that are displayed to the end-user of an application. These errors should be clear, concise, and provide useful information about what went wrong. A good user-facing error message should include the following elements:

  • A clear description of the error
  • Instructions on how to fix the error, if possible
  • A unique error code or identifier, if applicable

For example, a bad user-facing error message might be:

An error occurred. Please try again later.

This message is unhelpful because it doesn't provide any information about what went wrong or how to fix it. A better example would be:

Failed to connect to the server. Please check your internet connection and try again. (Error code: 500)

This message is more informative and provides a clear description of the error, as well as instructions on how to fix it.

Developer-Facing Errors

Developer-facing errors are those that are displayed to developers, usually in the form of stack traces or debug logs. These errors should be detailed and provide as much information as possible about what went wrong. A good developer-facing error message should include the following elements:

  • A detailed description of the error
  • The line of code where the error occurred
  • Relevant variables or data that may have contributed to the error

For example, a bad developer-facing error message might be:

Error on line 10

This message is unhelpful because it doesn't provide any information about what went wrong or how to fix it. A better example would be:

TypeError: Cannot read property 'length' of undefined on line 10 of file.js. Variable 'myArray' is undefined.

This message is more informative and provides a clear description of the error, as well as relevant information about the code that caused the error.

Log Messages

Log messages are used to record events or errors in an application. These messages should be concise and provide relevant information about the event or error. A good log message should include the following elements:

  • A timestamp of when the event or error occurred
  • A description of the event or error
  • Relevant variables or data that may have contributed to the event or error

For example, a bad log message might be:

Something went wrong

This message is unhelpful because it doesn't provide any information about what went wrong or when it happened. A better example would be:

2022-01-01 12:00:00 - Error occurred while processing request. User ID: 123, Request ID: 456

This message is more informative and provides a clear description of the event, as well as relevant information about the request that caused the event.

API Error Responses

API error responses are used to communicate errors to clients that are making requests to an API. These responses should be standardized and provide relevant information about the error. A good API error response should include the following elements:

  • A unique error code or identifier
  • A clear description of the error
  • Relevant information about the request that caused the error

For example, a bad API error response might be:

{
  "error": "Something went wrong"
}

This response is unhelpful because it doesn't provide any information about what went wrong or how to fix it. A better example would be:

{
  "error": {
    "code": 400,
    "message": "Invalid request parameters",
    "details": {
      "parameter": "name",
      "value": ""
    }
  }
}

This response is more informative and provides a clear description of the error, as well as relevant information about the request that caused the error.

Practical Takeaways

When writing error messages, it's essential to consider the audience and the context in which the error will be displayed. User-facing errors should be clear and concise, while developer-facing errors should be detailed and provide as much information as possible. Log messages and API error responses should be standardized and provide relevant information about the event or error. By following these guidelines, you can write error messages that are helpful and informative, which will improve the overall user experience and make it easier to debug and fix errors.