feat(V2): error envelope module estratto da server.py

src/cerbero_mcp/common/errors.py

@@ -0,0 +1,51 @@
+"""Error envelope standard per tutti i tool MCP."""
+from __future__ import annotations
+
+import uuid
+from datetime import UTC, datetime
+from typing import Any
+
+
+def error_envelope(
+    *,
+    type_: str,
+    code: str,
+    message: str,
+    retryable: bool,
+    suggested_fix: str | None = None,
+    details: dict | None = None,
+    request_id: str | None = None,
+) -> dict:
+    env: dict[str, Any] = {
+        "error": {
+            "type": type_,
+            "code": code,
+            "message": message,
+            "retryable": retryable,
+        },
+        "request_id": request_id or uuid.uuid4().hex,
+        "data_timestamp": datetime.now(UTC).isoformat(),
+    }
+    if suggested_fix:
+        env["error"]["suggested_fix"] = suggested_fix
+    if details:
+        env["error"]["details"] = details
+    return env
+
+
+HTTP_CODE_MAP = {
+    400: "BAD_REQUEST",
+    401: "UNAUTHORIZED",
+    403: "FORBIDDEN",
+    404: "NOT_FOUND",
+    408: "TIMEOUT",
+    409: "CONFLICT",
+    422: "VALIDATION_ERROR",
+    429: "RATE_LIMIT",
+    500: "INTERNAL_ERROR",
+    502: "UPSTREAM_ERROR",
+    503: "UNAVAILABLE",
+    504: "GATEWAY_TIMEOUT",
+}
+
+RETRYABLE_STATUSES = frozenset({408, 429, 502, 503, 504})