BerriAI/litellm · error · HTTPException

Service Unavailable, the authentication database is temporar

Error message

Service Unavailable, the authentication database is temporarily unreachable. Please retry shortly.

What it means

HTTP 503 raised by the DB-availability mapper when the caught exception indicates the auth database is unreachable: it is deliberately surfaced as a retryable Service Unavailable rather than a misleading 401 auth failure or opaque 500.

Source

Thrown at litellm/proxy/_experimental/mcp_server/auth/user_api_key_auth_mcp.py:1066

        if not MCPRequestHandler._admitted_key_is_active(key_object):
            raise HTTPException(status_code=401, detail="Invalid or expired credential")
        await MCPRequestHandler._reject_if_admitted_owner_scim_deactivated(key_object)
        return key_object

    @staticmethod
    def _raise_503_if_db_unavailable(e: Exception) -> None:
        """Raise a retryable 503 when ``e`` means the auth database is unreachable, else return so the
        caller applies its own fail-closed mapping. A DB outage must not masquerade as an auth failure
        (401) or surface as an opaque 500; the caller retries. Mirrors ``UserAPIKeyAuthExceptionHandler``,
        which renders a service-unavailable database error as 503 on the standard pipeline.

        Classifies across the ``__cause__``/``__context__`` chain, not just ``e`` itself: ``get_user_object``
        re-raises every DB failure as a bare ``ValueError``, so a type-based check on the top exception
        would miss a real outage wrapped inside it."""
        from litellm.proxy.db.exception_handler import PrismaDBExceptionHandler

        if PrismaDBExceptionHandler.is_database_service_unavailable_error_in_chain(e):
            raise HTTPException(
                status_code=503,
                detail="Service Unavailable, the authentication database is temporarily unreachable. Please retry shortly.",
            ) from None

    @staticmethod
    async def _reject_if_admitted_owner_scim_deactivated(key_object: UserAPIKeyAuth) -> None:
        """Fail closed with a 401 when the key's owning user was deactivated via SCIM.

        The standard pipeline enforces this inline in ``_user_api_key_auth_builder`` rather
        than in ``common_checks``, so the centralized policy gate does not cover it; without
        this mirror, IdP offboarding would leave the user's already-minted envelopes live
        until expiry. A failed user lookup skips the gate (fail-open), matching the builder:
        this is the one deliberately fail-open check in an otherwise fail-closed arm, so a
        transient DB outage during this lookup admits the request rather than rejecting it,
        keeping parity with how the standard pipeline treats the same lookup failure."""
        if key_object.user_id is None:
            return
        from litellm.proxy.auth.auth_checks import get_user_object

View on GitHub (pinned to 77b7c6c40c)

Solutions

1. Retry shortly; check database health and connectivity.
2. If persistent, fail over or restore the auth database.

Example fix

Retry with exponential backoff; check DB logs.

When it happens

Trigger: Thrown at litellm/proxy/_experimental/mcp_server/auth/user_api_key_auth_mcp.py:1066 when the library encounters an invalid state.

Common situations: See trigger scenarios.

Understand the failure class

• HTTP status errors: handling 4xx and 5xx responses — how to handle 4xx and 5xx responses properly.
• Authentication and authorization failures — expired tokens, bad credentials, and missing scopes.

AI-assisted analysis of BerriAI/litellm@77b7c6c40c (2026-08-18). Data as JSON: /api/errors/f1c7bf16c2191d67. Report an issue: GitHub.