Add detailed error mapping debug logs.

Will show exact exception type and mapping path.

Co-Authored-By: Claude Opus 4.7 <noreply@anthropic.com>

providers/error_mapping.py

@@ -38,39 +38,58 @@ def map_error(
     so reactive 429 handling applies to the correct provider. Tests may omit
     ``rate_limiter`` to use the process-wide singleton.
     """
+    from loguru import logger
+
     message = get_user_facing_error_message(e)
+    logger.info(
+        "map_error: original_exc_type={} message={}", type(e).__name__, message[:100]
+    )
     limiter = rate_limiter or GlobalRateLimiter.get_instance()
 
     if isinstance(e, openai.AuthenticationError):
+        logger.info("map_error: mapped to AuthenticationError")
         return AuthenticationError(message, raw_error=str(e))
     if isinstance(e, openai.RateLimitError):
         limiter.set_blocked(60)
+        logger.info("map_error: mapped to RateLimitError")
         return RateLimitError(message, raw_error=str(e))
     if isinstance(e, openai.BadRequestError):
+        logger.info("map_error: mapped to InvalidRequestError")
         return InvalidRequestError(message, raw_error=str(e))
     if isinstance(e, openai.InternalServerError):
         raw_message = str(e)
         if "overloaded" in raw_message.lower() or "capacity" in raw_message.lower():
+            logger.info("map_error: mapped to OverloadedError")
             return OverloadedError(message, raw_error=raw_message)
+        logger.info("map_error: mapped to APIError (InternalServerError)")
         return APIError(message, status_code=500, raw_error=str(e))
     if isinstance(e, openai.APIError):
+        logger.info("map_error: mapped to APIError (openai.APIError)")
         return APIError(
             message, status_code=getattr(e, "status_code", 500), raw_error=str(e)
         )
 
     if isinstance(e, httpx.HTTPStatusError):
         status = e.response.status_code
+        logger.info("map_error: httpx.HTTPStatusError status={}", status)
         if status in (401, 403):
+            logger.info("map_error: mapped to AuthenticationError (httpx)")
             return AuthenticationError(message, raw_error=str(e))
         if status == 429:
             limiter.set_blocked(60)
+            logger.info("map_error: mapped to RateLimitError (httpx)")
             return RateLimitError(message, raw_error=str(e))
         if status == 400:
+            logger.info("map_error: mapped to InvalidRequestError (httpx)")
             return InvalidRequestError(message, raw_error=str(e))
         if status >= 500:
             if status in (502, 503, 504):
+                logger.info("map_error: mapped to OverloadedError (httpx)")
                 return OverloadedError(message, raw_error=str(e))
+            logger.info("map_error: mapped to APIError (httpx 5xx)")
             return APIError(message, status_code=status, raw_error=str(e))
+        logger.info("map_error: mapped to APIError (httpx)")
         return APIError(message, status_code=status, raw_error=str(e))
 
+    logger.info("map_error: falling through, returning original exception")
     return e