Documentation for Custom http status code

src/main/docs/guide/httpServer/customHttpStatusCode

@@ -0,0 +1,38 @@
+The Micronaut framework supports custom HTTP status codes. This feature enables developers to define and use HTTP status codes beyond the standard ones, allowing integration with systems or APIs that rely on non-standard status codes.
+=== Custom HTTP Status Codes
+Micronaut supports arbitrary HTTP status codes that are not part of the predefined `HttpStatus` enum. Developers can specify any valid HTTP status code within the range `100-599`.
+
+==== Usage
+- `HttpResponse.status(int statusCode)`:
+Allows setting a custom HTTP status code.
+- `HttpResponse.status(int statusCode, String reason)`:
+Allows setting a custom HTTP status code along with a reason phrase.
+
+Below we can see how we support custom status codes and how to implement them. 
+
+snippet::io.micronaut.http.HttpResponse[tags="getStatusMethod", indent=0, title="HttpResponse.java"]
+Let's start with a simple example. Given the following class:
+
+snippet::io.micronaut.http.client.netty.FullNettyClientHttpResponse[tags="getBodyMethod", indent=0, title="FullNettyClientHttpResponse.java"]
+Note how we use code() in the condition where we are checkimg custom http status code. 
+
+snippet::io.micronaut.http.client.InvalidStatusSpec[tags="testInvalidStatus", indent=0, title="InvalidStatusSpec.groovy"]
+This snippet includes a test for handling an invalid HTTP status code in a Micronaut application.
+
+=== Client Response Handling
+The HTTP client in Micronaut can process custom status codes returned by servers. Custom codes are treated appropriately based on their range:
+- Codes `<400` are treated as successful responses.
+- Codes `>=400` trigger exceptions.
+
+==== Example
+[source,java]
+----
+try {
+    HttpResponse response = httpClient.toBlocking().exchange("/example");
+    int statusCode = response.code();
+} catch (HttpClientResponseException e) {
+    if (e.code() == 450) {
+        // Handle custom status code
+    }
+}
+----

src/main/docs/guide/toc.yml

@@ -109,6 +109,7 @@ httpServer:
   statusAnnotation: Response Status
   producesAnnotation: Response Content-Type
   consumesAnnotation: Accepted Request Content-Type
+  customHttpStatusCode: Supporting Custom Http Status Code
   reactiveServer:
     title: Reactive HTTP Request Processing
     bodyAnnotation: Using the @Body Annotation