Skip to content

Commit

Permalink
Update Rule “do-you-return-detailed-error-messages/rule” (#6935)
Browse files Browse the repository at this point in the history 
* Update Rule “do-you-return-detailed-error-messages/rule”

* small formatting improvements

---------

Co-authored-by: Tiago Araújo [SSW] <[email protected]>
  • Loading branch information
@christoment @tiagov8
christoment and tiagov8 authored Oct 9, 2023
1 parent c8ccd6a commit 986fe26
Showing 1 changed file with 28 additions and 31 deletions.
59 changes: 28 additions & 31 deletions rules/do-you-return-detailed-error-messages/rule.md
View file
Original file line number Diff line number Diff line change
@@ -1,44 +1,47 @@
---
type: rule
archivedreason:
title: Do you return detailed error messages?
guid: 7af36676-1eed-48dd-854b-2a956ef10e50
uri: do-you-return-detailed-error-messages
created: 2015-08-27T01:00:17.0000000Z
authors:
- title: Jeremy Cade
url: https://ssw.com.au/people/jeremy-cade
- title: Chris Clement
url: https://www.ssw.com.au/people/chris-clement
- title: Jeremy Cade
url: https://ssw.com.au/people/jeremy-cade
- title: Chris Clement
url: https://www.ssw.com.au/people/chris-clement
related: []
redirects: []

created: 2015-08-27T01:00:17.000Z
archivedreason: null
guid: 7af36676-1eed-48dd-854b-2a956ef10e50
---

Good error design is as important to the success of an API as the API design itself. A good error message provides context and visibility on how to troubleshoot and resolve issues at critical times.

<!--endintro-->

## REST API

### Use the correct HTTP Status Codes

The HTTP/1.1 RFC lists over 70 different HTTP Status Codes. Only some developers will be able to remember all of them, so it pays to keep it simple and use the most common Status Codes. Below are the most common HTTP status codes:

* **2XX** - Success. Examples:

* 200 OK - Generic success response.
* **4XX** - Client errors. Examples:

* 400 Bad Request - The server cannot understand the request.
* 401 Unauthorised - Invalid/non-existent credential for this request.
* **5XX** - Server errors. Examples:
* 500 Internal Server Error - The server encountered errors preventing the request from being fulfilled.

* 500 Internal Server Error - The server encountered errors preventing the request from being fulfilled.

### Use ProblemDetails Format

[RFC 7807 - Problem Details for HTTP APIs](https://www.rfc-editor.org/rfc/rfc7807.html) details the specification for returning errors from your API.

Problem Details defines a standardised way for HTTP APIs to communicate errors to clients. It introduces a simple and consistent format for describing errors, providing developers with a clear and uniform way to understand and handle errors in HTTP APIs.

Below is an example of an error message in Problem Details format:

```json
{
"type": "https://example.com/probs/invalid-id",
Expand All @@ -51,15 +54,15 @@ Below is an example of an error message in Problem Details format:
```

In the above example:
- `type` specifies a URI that uniquely identifies the type of the problem.
- `title` provides a short, human-readable summary of the problem.
- `status` indicates the HTTP status code for the response.
- `detail` gives a human-readable explanation specific to the occurrence of the problem.
- `instance` provides a URI reference that identifies the specific occurrence of the problem.
- `allowedCharacters` is an example property specificly added to the problem.

Using the above structured message format, APIs can now reliably communicate problems to clients to enable better error handling.
* `type` specifies a URI that uniquely identifies the type of the problem.
* `title` provides a short, human-readable summary of the problem.
* `status` indicates the HTTP status code for the response.
* `detail` gives a human-readable explanation specific to the occurrence of the problem.
* `instance` provides a URI reference that identifies the specific occurrence of the problem.
* `allowedCharacters` is an example property specificly added to the problem.

Using the above structured message format, APIs can now reliably communicate problems to clients to enable better error handling.

### Use .NET Exception Handler

Expand All @@ -83,10 +86,8 @@ Using this option, the API will generate a problem details response for all HTTP

You can also customise the `ProblemDetailsService` behaviour - read more about it in the following link [Handle errors in ASP.NET Core | Customise Problem Details](https://learn.microsoft.com/en-us/aspnet/core/fundamentals/error-handling?view=aspnetcore-8.0#customize-problem-details).


⚠️ **Important**
The default .NET Exception Handler middleware will **only** produce ProblemDetails responses for exceptions when running in a non-Development [environment](https://learn.microsoft.com/en-us/aspnet/core/fundamentals/environments?view=aspnetcore-7.0#environments). See Option 2 below on how to make this consistent across environments.

On certain templates, the default .NET Exception Handler middleware will **only** produce ProblemDetails responses for exceptions when running in a non-Development [environment](https://learn.microsoft.com/en-us/aspnet/core/fundamentals/environments?view=aspnetcore-7.0#environments). See Option 2 below on how to make this consistent across environments.

### Option 2 - Customise Exception Handler Middleware (Recommended)

Expand Down Expand Up @@ -114,7 +115,6 @@ app.UseExceptionHandler(exceptionHandlerApp =>
API will produce consistent response formats in any environment using the above approach.
This approach is the recommended approach for frontend and backend development.


## Any API (REST, gRPC and GraphQL):

### Add Sufficient Details in Error Message
Expand All @@ -128,7 +128,7 @@ Error messages should contain sufficient information that a developer or consumi
```

::: bad
Figure: Bad Example - The error message does not contain information that can be acted upon.
Figure: Bad example - The error message does not contain information that can be acted upon
:::

```json
Expand All @@ -138,7 +138,7 @@ Figure: Bad Example - The error message does not contain information that can be
```

::: good
Figure: Good Example - The error message provides explicit detail and a short description on how to fix the issue.
Figure: Good example - The error message provides explicit detail and a short description on how to fix the issue
:::

### Sanitize Response
Expand Down Expand Up @@ -176,8 +176,7 @@ User-Agent: curl/7.55.1
```

::: bad
Figure: Bad Example - this level of data should not be returned in a production environment

Figure: Bad example - this level of data should not be returned in a production environment
:::

### Provide a Tracking or Correlation ID
Expand All @@ -191,7 +190,7 @@ A tracking or correlation ID will allow the consuming clients to provide the AP
```

::: bad
Figure: Bad Example - No tracking or correlation ID is provided.
Figure: Bad example - No tracking or correlation ID is provided
:::

```json
Expand All @@ -202,7 +201,7 @@ Figure: Bad Example - No tracking or correlation ID is provided.
```

::: good
Figure: Good Exmaple - A error ID is provided as part of the reponse.
Figure: Good exmaple - A error ID is provided as part of the reponse
:::

### Provide an additional Help Resource
Expand All @@ -219,8 +218,7 @@ Providing a URI to an additional help resources as part of your request will all
```

::: bad
``Figure: Bad Example - No Help Link Provided

Figure: Bad example - No help link provided
:::

```json
Expand All @@ -234,6 +232,5 @@ Providing a URI to an additional help resources as part of your request will all
```

::: good
Figure: Good Example - A help link is provided as part of the response.

Figure: Good example - A help link is provided as part of the response
:::

0 comments on commit 986fe26

Please sign in to comment.