BerriAI/litellm · error · ServiceUnavailableError

ServiceUnavailableError: {exception_provider} - {error_str}

Error message

ServiceUnavailableError: {exception_provider} - {error_str}

What it means

LiteLLM re-raises the upstream provider's HTTP 503 as a ServiceUnavailableError. This happens inside get_llm_provider / exception mapping when the original exception carries status_code 503, meaning the provider or model endpoint is temporarily unable to serve the request (overloaded, down for maintenance, or a transient gateway failure).

Source

Thrown at litellm/litellm_core_utils/exception_mapping_utils.py:2129

            )
        elif original_exception.status_code == 422:
            raise BadRequestError(
                message=f"BadRequestError: {exception_provider} - {error_str}",
                model=model,
                llm_provider=custom_llm_provider,
                response=getattr(original_exception, "response", None),
                litellm_debug_info=extra_information,
            )
        elif original_exception.status_code == 429:
            raise RateLimitError(
                message=f"RateLimitError: {exception_provider} - {error_str}",
                model=model,
                llm_provider=custom_llm_provider,
                response=getattr(original_exception, "response", None),
                litellm_debug_info=extra_information,
            )
        elif original_exception.status_code == 503:
            raise ServiceUnavailableError(
                message=f"ServiceUnavailableError: {exception_provider} - {error_str}",
                model=model,
                llm_provider=custom_llm_provider,
                response=getattr(original_exception, "response", None),
                litellm_debug_info=extra_information,
            )
        elif original_exception.status_code == 504:  # gateway timeout error
            raise Timeout(
                message=f"Timeout Error: {exception_provider} - {error_str}",
                model=model,
                llm_provider=custom_llm_provider,
                litellm_debug_info=extra_information,
                exception_status_code=original_exception.status_code,
            )
        else:
            raise APIError(
                status_code=original_exception.status_code,
                message=f"APIError: {exception_provider} - {error_str}",

View on GitHub (pinned to 6c2dcb801b)

Solutions

Retry the request with exponential backoff (503 is transient by nature); litellm's built-in retries or a wrapper with 3-5 attempts usually resolves it.
If persistent, check the provider status page and confirm the model name is still offered.
Configure fallbacks (litellm.Router with fallback models) so a 503 on one model routes to another.
If behind your own proxy, inspect the proxy's health and upstream capacity.

Example fix

// before
const res = await litellm.completion({ model: 'gpt-4o', messages });

// after
const res = await retry(() => litellm.completion({ model: 'gpt-4o', messages }), { retries: 4, minTimeout: 1000, factor: 2 });

Defensive patterns

Strategy: retry

Try / catch

try {
  await litellm.completion(...);
} catch (e) {
  if (e instanceof litellm.ServiceUnavailableError) { /* backoff and retry, then failover */ }
}

Prevention

Wrap calls in exponential-backoff retry (e.g. tenacity) targeting ServiceUnavailableError.
Configure Router fallbacks so a 503 model fails over to a healthy one.
Monitor provider status and route away from degraded models.

When it happens

Trigger: Any litellm.completion()/acompletion() call whose underlying HTTP response or SDK exception has status_code == 503 (e.g. OpenAI/Anthropic/Azure returning 503, or an OpenAI-compatible proxy returning 'service unavailable').

Common situations: Hitting an overloaded model (capacity limits), calling a model that is deprecated/paused, an upstream reverse proxy (nginx, LiteLLM proxy) returning 503, or short outages at the provider.

Related errors

AI-assisted analysis of BerriAI/litellm@6c2dcb801b (2026-08-15). Data as JSON: /api/errors/ed3564a0faeba0e6. Report an issue: GitHub.