## 27) Error response body shape is inconsistent

backend/app/models/response.py

@@ -205,3 +205,48 @@ class CommandResponse(BanGuiBaseModel):
         default=True,
         description="Whether the command succeeded (false for errors in non-exception handlers).",
     )
+
+
+class ErrorResponse(BanGuiBaseModel):
+    """Standardized error response envelope for all API errors.
+
+    Use this for all error responses to ensure consistent client-side error handling.
+    The error code enables machine-readable branching, while detail provides
+    human-readable context. Metadata offers optional structured context.
+
+    Fields:
+        code: Machine-readable error code (e.g., "jail_not_found", "invalid_input").
+        detail: Human-readable error description for display to users.
+        metadata: Optional structured context (e.g., field names, constraint violations).
+
+    Example:
+        ```python
+        # 404 Not Found
+        {
+          "code": "jail_not_found",
+          "detail": "Jail 'sshd' not found",
+          "metadata": {"jail_name": "sshd"}
+        }
+
+        # 400 Bad Request - Validation Error
+        {
+          "code": "invalid_input",
+          "detail": "Invalid IP address format",
+          "metadata": {"field": "ip", "value": "999.999.999.999"}
+        }
+
+        # 409 Conflict
+        {
+          "code": "jail_already_active",
+          "detail": "Jail is already active: 'sshd'",
+          "metadata": {"jail_name": "sshd", "current_status": "active"}
+        }
+        ```
+    """
+
+    code: str = Field(..., description="Machine-readable error code for client-side branching.")
+    detail: str = Field(..., description="Human-readable error description.")
+    metadata: dict[str, str | int | float | bool | None] = Field(
+        default_factory=dict,
+        description="Optional structured context for the error.",
+    )