diff --git a/decnet/web/router/__init__.py b/decnet/web/router/__init__.py
index c732b34..cbbb99c 100644
--- a/decnet/web/router/__init__.py
+++ b/decnet/web/router/__init__.py
@@ -30,8 +30,11 @@ api_router = APIRouter(
     # require_* Depends or by the global auth middleware). Document 401/403
     # here so the OpenAPI schema reflects reality for contract tests.
     responses={
+        400: {"description": "Malformed request body"},
         401: {"description": "Missing or invalid credentials"},
         403: {"description": "Authenticated but not authorized"},
+        404: {"description": "Referenced resource does not exist"},
+        409: {"description": "Conflict with existing resource"},
     },
 )
 
diff --git a/decnet/web/router/fleet/api_deploy_deckies.py b/decnet/web/router/fleet/api_deploy_deckies.py
index 7c75ca8..5371ef7 100644
--- a/decnet/web/router/fleet/api_deploy_deckies.py
+++ b/decnet/web/router/fleet/api_deploy_deckies.py
@@ -26,7 +26,8 @@ router = APIRouter()
         403: {"description": "Insufficient permissions"},
         409: {"description": "Configuration conflict (e.g. invalid IP allocation or network mismatch)"},
         422: {"description": "Invalid INI config or schema validation error"},
-        500: {"description": "Deployment failed"}
+        500: {"description": "Deployment failed"},
+        502: {"description": "Partial swarm deploy failure — one or more worker hosts returned an error"},
     }
 )
 @_traced("api.deploy_deckies")