{"record":{"id":"ed3564a0faeba0e6","repo":"BerriAI/litellm","slug":"serviceunavailableerror-exception-provider-e","errorCode":null,"errorMessage":"ServiceUnavailableError: {exception_provider} - {error_str}","messagePattern":"ServiceUnavailableError: (.+?) - (.+?)","errorType":"exception","errorClass":"ServiceUnavailableError","httpStatus":503,"severity":"error","filePath":"litellm/litellm_core_utils/exception_mapping_utils.py","lineNumber":2129,"sourceCode":"            )\n        elif original_exception.status_code == 422:\n            raise BadRequestError(\n                message=f\"BadRequestError: {exception_provider} - {error_str}\",\n                model=model,\n                llm_provider=custom_llm_provider,\n                response=getattr(original_exception, \"response\", None),\n                litellm_debug_info=extra_information,\n            )\n        elif original_exception.status_code == 429:\n            raise RateLimitError(\n                message=f\"RateLimitError: {exception_provider} - {error_str}\",\n                model=model,\n                llm_provider=custom_llm_provider,\n                response=getattr(original_exception, \"response\", None),\n                litellm_debug_info=extra_information,\n            )\n        elif original_exception.status_code == 503:\n            raise ServiceUnavailableError(\n                message=f\"ServiceUnavailableError: {exception_provider} - {error_str}\",\n                model=model,\n                llm_provider=custom_llm_provider,\n                response=getattr(original_exception, \"response\", None),\n                litellm_debug_info=extra_information,\n            )\n        elif original_exception.status_code == 504:  # gateway timeout error\n            raise Timeout(\n                message=f\"Timeout Error: {exception_provider} - {error_str}\",\n                model=model,\n                llm_provider=custom_llm_provider,\n                litellm_debug_info=extra_information,\n                exception_status_code=original_exception.status_code,\n            )\n        else:\n            raise APIError(\n                status_code=original_exception.status_code,\n                message=f\"APIError: {exception_provider} - {error_str}\",","sourceCodeStart":2111,"sourceCodeEnd":2147,"githubUrl":"https://github.com/BerriAI/litellm/blob/6c2dcb801bf2b75c18f1bb24140e7cf57465cc4d/litellm/litellm_core_utils/exception_mapping_utils.py#L2111-L2147","documentation":"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).","triggerScenarios":"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').","commonSituations":"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.","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."],"exampleFix":"// before\nconst res = await litellm.completion({ model: 'gpt-4o', messages });\n\n// after\nconst res = await retry(() => litellm.completion({ model: 'gpt-4o', messages }), { retries: 4, minTimeout: 1000, factor: 2 });","handlingStrategy":"retry","validationCode":null,"typeGuard":null,"tryCatchPattern":"try {\n  await litellm.completion(...);\n} catch (e) {\n  if (e instanceof litellm.ServiceUnavailableError) { /* backoff and retry, then failover */ }\n}","preventionTips":["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."],"tags":["http-503","transient","provider-outage","retryable"],"backgroundTag":null,"analyzedSha":"6c2dcb801bf2b75c18f1bb24140e7cf57465cc4d","analyzedAt":"2026-08-15T07:12:03.035Z","schemaVersion":2},"datasetVersion":"2026-08-15T22:17:37.221Z"}