enhancing error parsing

Author: pint-drinker

subconscious/errors.py

@@ -76,27 +76,63 @@ def _status_to_code(status: int) -> ErrorCode:
 
 
 def raise_for_status(response) -> None:
-    """Raise appropriate exception based on response status."""
-    if response.status_code >= 400:
-        try:
-            body = response.json()
-            error = body.get("error", {})
-            code = error.get("code", _status_to_code(response.status_code))
-            message = error.get("message", response.text or f"HTTP {response.status_code}")
-            details = error.get("details")
-        except Exception:
-            code = _status_to_code(response.status_code)
-            message = response.text or f"HTTP {response.status_code}"
-            details = None
-
-        if code == "authentication_failed":
-            raise AuthenticationError(message)
-        elif code == "rate_limited":
-            raise RateLimitError(message)
-        elif code == "not_found":
-            raise NotFoundError(message)
-        elif code == "invalid_request":
-            raise ValidationError(message, details)
-        else:
-            raise SubconsciousError(code, message, response.status_code, details)
+    """Raise appropriate exception based on response status.
+
+    Extracts error info from three wire shapes the server may return:
+
+    - Canonical SDK shape: ``{"error": {"code", "message", "details"}}``
+    - Express default:     ``{"error": "Internal server error"}``
+    - Plain text/unknown:  falls back to ``response.text``
+
+    Enriches the message with method + URL so users get enough context
+    to correlate with server logs (especially for 5xx responses where
+    the body is generic).
+    """
+    if response.status_code < 400:
+        return
+
+    try:
+        body = response.json()
+    except Exception:
+        body = None
+
+    error_field = body.get("error") if isinstance(body, dict) else None
+    if isinstance(error_field, dict):
+        code = error_field.get("code", _status_to_code(response.status_code))
+        message = error_field.get("message") or str(error_field)
+        details = error_field.get("details")
+    elif isinstance(error_field, str):
+        code = _status_to_code(response.status_code)
+        message = error_field
+        details = None
+    else:
+        code = _status_to_code(response.status_code)
+        message = response.text or f"HTTP {response.status_code}"
+        details = None
+
+    # Context suffix: "[GET /v1/runs/<id>]" and a request id when the
+    # server surfaces one. Skipped quietly if the request object isn't
+    # reachable (e.g., requests.Response without a bound PreparedRequest).
+    request = getattr(response, "request", None)
+    method = getattr(request, "method", None)
+    url = getattr(request, "url", None)
+    request_id = response.headers.get("x-request-id") if response.headers else None
+    suffix_parts = []
+    if method and url:
+        suffix_parts.append(f"{method} {url}")
+    if request_id:
+        suffix_parts.append(f"request_id={request_id}")
+    if suffix_parts:
+        message = f"{message} [{' '.join(suffix_parts)}]"
+
+    if code == "authentication_failed":
+        raise AuthenticationError(message)
+    elif code == "rate_limited":
+        raise RateLimitError(message)
+    elif code == "not_found":
+        raise NotFoundError(message)
+    elif code == "invalid_request":
+        raise ValidationError(message, details)
+    else:
+        raise SubconsciousError(code, message, response.status_code, details)