`litellm.ServiceUnavailableError` — LiteLLM mapped a provider error to its 503 class

litellm.ServiceUnavailableError: ServiceUnavailableError: <Provider>Exception - <provider message>

(The error as str(e) gives it when it comes from LiteLLM’s generic status-503 branch for OpenAI-style providers, assembled by us from two prefixes quoted as source below, with our placeholders in angle brackets. The doubled name is the class prefix followed by the branch’s own prefix. Other raise sites build a different text after litellm.ServiceUnavailableError: .)

In its exception mapper, LiteLLM raises this after the provider call failed: it maps the provider’s exception to its own classes, and the class it picks is ServiceUnavailableError when the provider’s exception carries status code 503 in the generic branch, and in a number of provider-specific branches on status 503, on status 500, 504 or 520, or on a phrase in the error text, listed below. Every claim about the library below is read off the Python source of BerriAI/litellm at tag v1.104.2, fetched on 10 October 2026, with the line of each quote given; where we draw a conclusion from those lines rather than quote them, we say so.

What it is: class ServiceUnavailableError(openai.APIStatusError):, in litellm/exceptions.py — a subclass of the OpenAI SDK’s APIStatusError, not of a 503-specific OpenAI class. Its constructor prefixes the message with litellm.ServiceUnavailableError: and sets self.status_code = 503 whatever the raise passed.

Where: exception_type in litellm_core_utils/exception_mapping_utils.py, which completion() raises from its except block; that file has 16 raise statements for this class, in two spellings, listed below.

What to check: the provider’s own text at the end of the message, which says what actually failed, and e.llm_provider and e.model for which deployment it was; then decide whether a retry with backoff is worth it (our reading).

The generic raise

In litellm/litellm_core_utils/exception_mapping_utils.py, inside _map_openai_exception (defined at line 275), lines 490–492:

elif original_exception.status_code == 503: raise ServiceUnavailableError( message=f"ServiceUnavailableError: {exception_provider} - {message}",

That elif is inside elif hasattr(original_exception, "status_code"): (line 422), which belongs to the chain that opens at line 307 with if ExceptionCheckers.is_error_str_rate_limit(. So this raise runs when the original exception has a status_code attribute equal to 503 and none of the earlier branches of that chain (lines 307–421) matched — among them the rate-limit test on the error text and the status code (lines 307–309) and the context-window test on the error text (line 317) (our reading). The raise passes model=model,, llm_provider=custom_llm_provider,, response=response, and litellm_debug_info=extra_information, (lines 493–496); response is what _litellm_proxy_response returns for the original exception (line 285). In the same function, message is what get_error_message returns for the original exception, or failing that its message attribute or str() (lines 287–292), with OPENAI and openai.OpenAIError replaced by the upper-cased provider name and by {custom_llm_provider}.{custom_llm_provider}Error when the message is a string (lines 294–301); exception_provider is "OpenAI" + "Exception" for openai and otherwise the provider name with its first letter upper-cased plus Exception (lines 302–305). exception_type (line 2349) sends openai, text-completion-openai, custom_openai, mistral, runwayml and the providers in litellm.openai_compatible_providers to this function (the condition at lines 2458–2465).

The other sites in that file

A grep of the file for raise ServiceUnavailableError( finds lines 491, 714, 838, 966, 1018, 1072, 1126, 1359, 1546, 1700, 1853, 1885, 2104, 2198 and 2315, and for raise litellm.ServiceUnavailableError( line 625; no other line constructs the class. We take both spellings to name the class in litellm/exceptions.py: the file imports ServiceUnavailableError from ..exceptions (lines 21–36); we did not fetch the package’s __init__.py (our inference for the litellm. spelling). Besides line 491:

Anthropic — in _map_anthropic_exception, line 625, inside if hasattr(original_exception, "status_code"): (line 571), under elif original_exception.status_code == 503: (line 624), lines 625–626:

raise litellm.ServiceUnavailableError( message=f"AnthropicException - {error_str}. Handle with `litellm.ServiceUnavailableError`.",

Replicate — in _map_replicate_exception, line 714, under elif original_exception.status_code == 500: (line 713) inside elif hasattr(original_exception, "status_code"): (line 678).
OpenAI-like providers — in _map_openai_like_exception, line 838, under elif original_exception.status_code == 503: (line 837) inside elif hasattr(original_exception, "status_code"): (line 784).
Bedrock — in _map_bedrock_exception, inside elif hasattr(original_exception, "status_code"): (line 964): line 966, under if original_exception.status_code == 500: (line 965), and line 1018, under elif original_exception.status_code == 503: (line 1017).
SageMaker — in _map_sagemaker_exception, inside elif hasattr(original_exception, "status_code"): (line 1070): line 1072, under if original_exception.status_code == 500: (line 1071), and line 1126, under elif original_exception.status_code == 503: (line 1125).
Vertex AI and Gemini — in _map_vertex_exception, line 1359, under if original_exception.status_code == 503: (line 1358) inside if hasattr(original_exception, "status_code"): (line 1279).
Hugging Face — in _map_huggingface_exception, line 1546, under elif original_exception.status_code == 503: (line 1545) inside if hasattr(original_exception, "status_code"): (line 1517).
NLP Cloud — in _map_nlp_cloud_exception, line 1700, under elif original_exception.status_code == 504 or original_exception.status_code == 520: (line 1699).
Aleph Alpha — in _map_aleph_alpha_exception, line 1853, under elif original_exception.status_code == 500: (line 1852).
Ollama — in _map_ollama_exception, line 1885, under elif "Failed to establish a new connection" in error_str: (line 1884), reached when the test before it (line 1877) did not match; no status code is tested there.
Azure — in _map_azure_exception, line 2104, under elif original_exception.status_code == 503: (line 2103) inside elif hasattr(original_exception, "status_code"): (line 2046), with the message f"AzureException ServiceUnavailableError - {message}" (line 2105).
OpenRouter — in _map_openrouter_exception, line 2198, under elif original_exception.status_code == 503: (line 2197) inside if hasattr(original_exception, "status_code"): (line 2149), with the message f"ServiceUnavailableError: {exception_provider} - {error_str}" (line 2199). This function is called from its own if custom_llm_provider == "openrouter": (line 2639), after the provider if/elif chain, so only when nothing in that chain raised (our reading).
The fallback in exception_type — line 2315, in _map_exception_by_status, described in the next section.

The Replicate, Bedrock (line 966), SageMaker (line 1072), NLP Cloud and Aleph Alpha branches test for 500, 504 or 520, and the Ollama branch tests the error text, so the class does not by itself tell you the provider sent 503 (our reading).

The fallback for status 503

In exception_type, after the if model or custom_llm_provider: block (line 2376) that holds the provider-specific mapping — so only when nothing in that block raised (our reading) — line 2649 tests the error for a BadRequestError.__init__() message, and the else: of that test, line 2659, sets exception_mapping_worked = True (line 2663) and calls _map_exception_by_status (line 2664). That function (line 2242) returns without raising when the status code is not an int or is below 400, or when status_code_is_synthesized is true (lines 2251–2255); otherwise it builds message: Final = f"{exception_provider} - {error_str}" (line 2256) and, under case 503: (line 2314), raises this class at line 2315. Here exception_provider is the provider name with its first letter upper-cased plus Exception when the provider name is a non-empty string, set inside the try: at line 2392 (lines 2402–2403), and the provider name as passed otherwise (line 2360). This message has no inner ServiceUnavailableError:, so str(e) reads litellm.ServiceUnavailableError: <Provider>Exception - <error text> (our reading, our placeholders).

Every raise above happens inside the try: at line 2373, from which the mapper functions are called (our reading). Its except Exception as e: (line 2700) re-raises e when exception_mapping_worked is true (lines 2712–2714) and otherwise when e is an instance of a type in litellm.LITELLM_EXCEPTION_TYPES (lines 2716–2719), a list that includes ServiceUnavailableError (exceptions.py line 983); both paths first set litellm_response_headers on it. So the class reaches the caller unchanged from every site above (our reading).

Where `completion()` sends it

In litellm/main.py, completion (line 5113) ends with, lines 6036–6038:

except Exception as e: ## Map to OpenAI Exception raise exception_type(

passing model, custom_llm_provider and the original exception (lines 6038–6044). acompletion (line 400) does the same at lines 709–717, after setting custom_llm_provider to "openai" when it is empty (line 710). exception_type returns an exception that is already one of LiteLLM’s types unchanged (lines 2357–2358), so an error mapped once is not mapped again (our reading). We did not trace the Router or the proxy.

The class

In litellm/exceptions.py, class ServiceUnavailableError(openai.APIStatusError): is at line 664. Its constructor takes message, llm_provider, model and optional response, litellm_debug_info, max_retries and num_retries (lines 665–674) — no body — then sets, lines 675–676:

self.status_code = 503 self.message = f"litellm.ServiceUnavailableError: {message}"

Lines 677–681 store llm_provider, model, litellm_debug_info, max_retries and num_retries as passed. Lines 682–690 build self.response as a new httpx.Response with status_code=self.status_code,, the headers of the response argument when one was passed, and a stub request to url=" https://cloud.google.com/vertex-ai/",; lines 691–693 pass self.message, response=self.response, body=None to the parent. The response the provider sent is not kept as e.response, only its headers (our reading of lines 682–693). Its __str__ (lines 695–701) and __repr__ (lines 703–709) return self.message, plus LiteLLM Retried: {self.num_retries} times when num_retries is non-zero and , LiteLLM Max Retries: {self.max_retries} when max_retries is non-zero (if self.num_retries:, if self.max_retries:).

The parent, in the OpenAI Python SDK at v1.109.1 (the version we read; yours may differ), is class APIStatusError(APIError): in src/openai/_exceptions.py (line 80). Its constructor (lines 87–91) passes the message, response.request and the body up to APIError, then sets self.response, self.status_code from response.status_code and self.request_id from the response’s x-request-id header; APIError.__init__ (lines 54–67) sets request, message and body, and sets code, param and type to None when the body is not a dict. With the stub response and body=None above, that makes e.status_code 503, e.request the stub request, e.body, e.code and e.type None, and e.request_id the provider’s x-request-id only if the passed response carried one (our reading, at that SDK version).

What it looks like in the field

In BerriAI/litellm#44184, titled [Bug]: OTel error spans have no status description, the error is only in error.message, the reporter runs the proxy (LiteLLM 1.103.2) against a local OpenAI-compatible stub that answers 503 for an openai/ model, and the proxy’s response reads litellm.ServiceUnavailableError: ServiceUnavailableError: OpenAIException - upstream is overloaded, try again later. The issue itself is about the OTel span, not the error.

In vectorize-io/hindsight#5009, titled LiteLLM provider doesn't retry Bedrock's transient ServiceUnavailableError (503 in status_code, no keyword in message), the reporter (LiteLLM 1.93.0, provider bedrock) shows litellm.ServiceUnavailableError: BedrockException - {"message":"The system encountered an unexpected error during processing. Try your request again."} and writes that their own retry code searched the exception text for keywords such as 503, found none, and so did not retry.

The first text has the shape of line 492, with the class prefix in front; the second the shape of the Bedrock messages at lines 967 and 1019, which are the same, so the text alone does not say which of the two ran (our reading). Both reports are on versions other than the v1.104.2 source read above.

What the caller sees and can read

str(e) and e.message — litellm.ServiceUnavailableError: followed by the message the raise passed (line 676); str(e) adds the retry notes when those counts are non-zero (lines 695–701).
e.status_code — 503, set at line 675 for every raise, including the branches that test 500, 504 or 520 and the Ollama branch that tests only the error text. It does not tell you what the provider returned (our reading).
e.response — the httpx.Response built at lines 683–690: status 503, the headers of whatever response the raise passed, and a stub request (our reading). The OpenAI-like (line 838) and Vertex AI (line 1359) sites pass no response, so there it has no provider headers (our reading).
e.llm_provider, e.model — what the raise passed (lines 677–678); at line 491 the custom_llm_provider and model that completion() passed to exception_type (lines 6039–6040), which get_llm_provider may have reassigned (line 5452); the Anthropic, Replicate, Hugging Face, NLP Cloud, Aleph Alpha, Ollama and Azure sites, and Bedrock’s line 966, pass a fixed provider name.
e.litellm_debug_info — what the raise passed (line 679). Lines 491, 838, 1018, 1126, 2104, 2198 and 2315 pass extra_information; the others pass nothing, so it is None, the default at line 671 (our reading). exception_type sets extra_information to "" (line 2375) and, inside the try: at line 2392, to f"\nModel: {model}" (line 2400) and, when litellm.get_api_base returned one (line 2393), extends it with f"\nAPI Base: `{_api_base}`" (line 2406), among other details.
e.litellm_response_headers — set in the except block above to what _get_response_headers (line 193) found on the original exception: its headers, else its response’s headers, else its own litellm_response_headers (lines 201–206), or None.

What to do

Read the provider part of the message. After the prefix comes <Provider>Exception - or the branch’s own label and the original error text, which says what actually failed: a 503 from the provider or a gateway in front of it, another status a provider branch maps here, or, for Ollama, a failed connection (our reading).
Catch the class, not a keyword. Test isinstance(e, ServiceUnavailableError) rather than searching the text for 503; the message the raise builds need not contain it, as in the Bedrock report above (our reading of lines 967 and 1019).
Do not branch on e.status_code to learn what the provider sent; it is 503 here whether the provider returned 503, 500, 504 or 520, or Ollama could not connect (our reading, from line 675 and the branches above).
Check which deployment it was with e.llm_provider, e.model and e.litellm_debug_info, which from line 491 carries the API base when LiteLLM found one (our reading of lines 496 and 2406).
Retry with backoff when the provider part points at the server side. main.py has completion_with_retries (lines 6047–6070), which wraps completion (unless an original_function is passed, line 6061) in tenacity.Retrying with stop_after_attempt(num_retries), num_retries defaulting to 3 (line 6056); with retry_strategy="exponential_backoff_retry" it waits tenacity.wait_exponential(multiplier=1, max=10) between attempts, and the default "constant_retry" (line 6060) passes no wait= (lines 6062–6069). Neither Retrying call passes a retry= condition, so it is not specific to this class (our reading). An Ollama connection failure needs the server running first. We say nothing here about any provider’s reliability.

from litellm import completion from litellm.exceptions import ServiceUnavailableError def call(model: str, messages: list[dict]): # Our sketch: show what LiteLLM knew when it mapped the error to its 503 class. try: return completion(model=model, messages=messages) except ServiceUnavailableError as e: print("provider:", e.llm_provider, "model:", e.model) print("debug info:", e.litellm_debug_info) print("headers:", getattr(e, "litellm_response_headers", None)) print(e.message) raise

(Our sketch, not library code, and not run against your version. It re-raises: whether to retry depends on what the provider part of the message says.)

What is behind this site

There is a written guide: the step-and-turn arithmetic as a formula you can run against a brief before you launch it, why raising a cap does not finish the job, and batch.py, one standard-library file that collapses a per-item loop into a single pass — fewer turns, which means fewer final calls made from an unfinished transcript when a run hits its cap. It is $19, on a storefront that delivers the files automatically and carries a 30-day money-back guarantee (checked 7 October 2026). One working way to pay today is 19 USDC on Base, and delivery is manual: you email the transaction hash and the files come back as a reply. This page is free, ungated, and sells nothing on its own.

The short version: litellm.ServiceUnavailableError is LiteLLM’s subclass of openai.APIStatusError, raised by exception_type — in the generic OpenAI-style branch when the provider’s exception has status_code 503 and matched no earlier test; in Anthropic, OpenAI-like, Bedrock, SageMaker, Vertex AI, Hugging Face, Azure and OpenRouter branches on status 503; in Replicate, Bedrock, SageMaker and Aleph Alpha branches on status 500; in NLP Cloud on 504 or 520; in Ollama on a failed-connection phrase; and in the status fallback for a 503. str(e) starts litellm.ServiceUnavailableError: and e.status_code is always 503. Read the provider’s text at the end of the message before you retry.

Nearby

litellm.InternalServerError — also from LiteLLM’s exception_type, but its object carries status_code 500 and the generic branch raises it for a provider status of 500; this one carries 503 and the generic branch raises it for 503.
litellm.APIConnectionError — also from LiteLLM’s exception_type, but raised in the generic branch when the provider’s exception had no status code at all; this one is raised for a status code, except in the Ollama branch, which raises it for a failed-connection phrase.
overloaded_error — the Claude API’s own HTTP 529 error; LiteLLM’s Anthropic branch raises litellm.InternalServerError, not this class, for status 529 or for that text in the error (lines 547 and 610), and this class for status 503 when no earlier test matched (line 624).

This page counts anonymous readership with one counter, the file at /measure.js, and each of the events below is sent at most once per load. Once the page is ready it sends one view event. With it go the page path, the domain of the page you came from — only the domain, and nothing at all if you came from this site — how long the page has been open, counting only the time it was actually in front of you and not the time it sat in a background tab, whether you have scrolled, and any campaign or outreach code in the link you followed. A second event, which we call a human candidate, is sent only once the page has also received a real input event from you — a mouse movement, a touch, a scroll or a key press — and has been visible in the foreground for ten seconds in all; a program that fetches the page, or opens it and sits there, cannot produce one. A third, “engaged”, is stricter still: it is sent only after the human-candidate event, once the page has been in front of you for ninety seconds in all and you have scrolled far enough to reach a marker we put where the explaining part of this page ends; a reader who stops short of that marker never produces one. The second and third events carry the same fields as the first. If you switch away from the tab or close it, an event that has just become due may be sent as you leave. If this page has a button or a copy control that says it records a click, pressing it sends the name of that event and nothing else. Following a link to buy the guide sends one further event, also at most once per load, carrying that event’s name and a single word for which of the two checkouts you were sent to — the Gumroad listing or the payment page on this site — and nothing else: not the address you followed, not which page you were reading, not how long you had been there. Everything is sent to this site only, with no cookie attached. No cookie is read or written, nothing is put in your browser’s local or session storage, and no identifier is made from your device. Earlier versions of this page kept the campaign codes of your first visit in local storage under the name llab_attr; this page neither reads nor deletes that entry, so if it is there it stays until you clear this site’s data. An outreach code is minted per recipient, which would let us tell one reader from another; it is sent with each event and, unlike on earlier versions of this page, it is no longer removed from the address bar after it is read — if you copy the address, the code goes with it. Earlier versions also asked this domain for Vercel’s analytics script at /_vercel/insights/script.js, which on 26 September 2026 returned HTTP 404 on every host we publish; this page no longer asks for it. Your browser and the network attach things the page does not send: the identification string your browser gives, your IP address and the time of the request. The host that serves this page keeps its own request logs; those are its record and not ours.

litellm.ServiceUnavailableError — LiteLLM mapped a provider error to its 503 class