Update Rule “do-you-return-detailed-error-messages/rule”

rules/do-you-return-detailed-error-messages/rule.md

@@ -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",
@@ -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
 
@@ -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)
 
@@ -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
@@ -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
@@ -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
@@ -191,7 +191,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
@@ -202,7 +202,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
@@ -219,7 +219,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
 
 :::
 
@@ -236,4 +236,4 @@ 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.
 
-:::
+:::