From c5a43ef2a0aea99e73685ff241cf7f7cd883bf7e Mon Sep 17 00:00:00 2001
From: TekH <h.tek@digitaldata.works>
Date: Sat, 10 Oct 2026 14:58:01 +0200
Subject: [PATCH] feat(api): surface 403/404/409 responses via middleware and
 docs

---
 .../Controllers/DocumentsController.cs                |  1 +
 .../Controllers/WorkflowsController.cs                |  3 +++
 .../Middleware/ExceptionHandlingMiddleware.cs         | 11 +++++++++++
 3 files changed, 15 insertions(+)

diff --git a/src/presentation/DigitalData.TaskFlow.API/Controllers/DocumentsController.cs b/src/presentation/DigitalData.TaskFlow.API/Controllers/DocumentsController.cs
index df545bb..83dd1d5 100644
--- a/src/presentation/DigitalData.TaskFlow.API/Controllers/DocumentsController.cs
+++ b/src/presentation/DigitalData.TaskFlow.API/Controllers/DocumentsController.cs
@@ -22,6 +22,7 @@ public sealed class DocumentsController(ISender sender) : ControllerBase
     [HttpGet("{id}")]
     [ProducesResponseType(typeof(FileContentResult), StatusCodes.Status200OK)]
     [ProducesResponseType(typeof(ApiEnvelope<object>), StatusCodes.Status400BadRequest)]
+    [ProducesResponseType(typeof(ApiEnvelope<object>), StatusCodes.Status404NotFound)]
     [ProducesResponseType(typeof(ApiEnvelope<object>), StatusCodes.Status500InternalServerError)]
     public async Task<IActionResult> GetAsync([FromRoute] string id, CancellationToken cancellationToken)
     {
diff --git a/src/presentation/DigitalData.TaskFlow.API/Controllers/WorkflowsController.cs b/src/presentation/DigitalData.TaskFlow.API/Controllers/WorkflowsController.cs
index c2f4f42..82c5712 100644
--- a/src/presentation/DigitalData.TaskFlow.API/Controllers/WorkflowsController.cs
+++ b/src/presentation/DigitalData.TaskFlow.API/Controllers/WorkflowsController.cs
@@ -46,6 +46,9 @@ public sealed class WorkflowsController(ISender sender) : ControllerBase
     [HttpPost("{wisagId:int}/{source}/{processId:int}/closing")]
     [ProducesResponseType(typeof(ApiEnvelope<CloseWorkflowResult>), StatusCodes.Status200OK)]
     [ProducesResponseType(typeof(ApiEnvelope<object>), StatusCodes.Status400BadRequest)]
+    [ProducesResponseType(typeof(ApiEnvelope<object>), StatusCodes.Status403Forbidden)]
+    [ProducesResponseType(typeof(ApiEnvelope<object>), StatusCodes.Status404NotFound)]
+    [ProducesResponseType(typeof(ApiEnvelope<object>), StatusCodes.Status409Conflict)]
     [ProducesResponseType(typeof(ApiEnvelope<object>), StatusCodes.Status500InternalServerError)]
     public async Task<ActionResult<ApiEnvelope<CloseWorkflowResult>>> CloseAsync(
         [FromRoute] int wisagId,
diff --git a/src/presentation/DigitalData.TaskFlow.API/Middleware/ExceptionHandlingMiddleware.cs b/src/presentation/DigitalData.TaskFlow.API/Middleware/ExceptionHandlingMiddleware.cs
index ca56f87..6153d37 100644
--- a/src/presentation/DigitalData.TaskFlow.API/Middleware/ExceptionHandlingMiddleware.cs
+++ b/src/presentation/DigitalData.TaskFlow.API/Middleware/ExceptionHandlingMiddleware.cs
@@ -1,3 +1,4 @@
+using DigitalData.TaskFlow.Application.Common.Exceptions;
 using DigitalData.TaskFlow.Application.Common.Factories;
 using DigitalData.TaskFlow.Domain.Common;
 using DigitalData.TaskFlow.Domain.Enums;
@@ -23,6 +24,16 @@ public sealed class ExceptionHandlingMiddleware(RequestDelegate next, ILogger<Ex
         {
             await next(context);
         }
+        catch (ApiException apiException)
+        {
+            logger.LogWarning(apiException, "API exception intercepted.");
+
+            context.Response.StatusCode = apiException.StatusCode;
+            context.Response.ContentType = "application/json";
+
+            var response = ApiEnvelopeFactory.Create<object?>(null, apiException.MetaCode, apiException.Message);
+            await context.Response.WriteAsync(JsonSerializer.Serialize(response, JsonOptions));
+        }
         catch (ValidationException validationException)
         {
             logger.LogWarning(validationException, "Validation failed.");