litellm - 💡(How to fix) Fix Gemini AI Studio 5xx responses leak as MaskedHTTPStatusError instead of ServiceUnavailableError (1.85.1)

Summary

When the Gemini AI Studio backend (generativelanguage.googleapis.com) returns a 5xx response, litellm.acompletion raises litellm.llms.custom_httpx.http_handler.MaskedHTTPStatusError instead of the typed litellm.exceptions.ServiceUnavailableError. Downstream code that wraps litellm.acompletion and catches litellm.exceptions.* cannot distinguish an upstream service-unavailable failure from any other unclassified error without also depending on the internal litellm.llms.custom_httpx.http_handler wrapper class.

Environment

• litellm==1.85.1
• Python 3.13
• Provider: gemini/gemini-3-flash-preview
• Upstream endpoint observed: https://generativelanguage.googleapis.com/v1alpha/models/gemini-3-flash-preview:generateContent

Reproduction

1. Configure LiteLLM with a Gemini model alias (gemini/gemini-3-flash-preview).
2. Issue an await litellm.acompletion(model="gemini/gemini-3-flash-preview", messages=[...]) at a time when the Google AI Studio backend returns 503.
3. Observe the exception type raised by acompletion.

Actual behavior

Traceback (most recent call last):
  File "/app/.venv/lib/python3.13/site-packages/litellm/llms/custom_httpx/http_handler.py", line 225, in async_completion
    response = await client.post(
               ^^^^^^^^^^^^^^^^^
  [...]
    raise MaskedHTTPStatusError(e, message=_text, text=_text) from None
litellm.llms.custom_httpx.http_handler.MaskedHTTPStatusError: Server error '503 Service Unavailable' for url 'https://generativelanguage.googleapis.com/v1alpha/models/gemini-3-flash-preview:generateContent'
For more information check: https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/503
{
  "error": {
    "code": 503,
    "message": "The service is currently unavailable.",
    "status": "UNAVAILABLE"
  }
}

The exception that escapes the acompletion boundary is the raw MaskedHTTPStatusError, not a litellm.exceptions.* subclass.

Expected behavior

litellm.exceptions.ServiceUnavailableError is raised, mirroring how RateLimitError, AuthenticationError, BadRequestError, NotFoundError, etc. are surfaced today for other providers. Callers should be able to:

from litellm.exceptions import ServiceUnavailableError

try:
    await litellm.acompletion(...)
except ServiceUnavailableError:
    ...

without importing from litellm.llms.custom_httpx.http_handler.

Observation

Other classified exceptions appear to work as expected for the same Gemini provider (e.g. BadRequestError, NotFoundError are surfaced typed). The 5xx path specifically is what we observe leaking as MaskedHTTPStatusError.