Exceptions: one set for every provider
LiteLLM exceptions are one set of error classes, copied from the OpenAI SDK, that LiteLLM raises whichever provider failed, so one except clause can handle every provider's errors.
Last updated: 12 Oct, 2026 · LiteLLM 1.105
Tokens and cost showed a function that raised. This lesson is about errors in general: providers fail in their own words, and LiteLLM turns each failure into one of its own classes. Each class here was raised by a real call.
Syntax: catch a LiteLLM class from the litellm module. Every one carries three extra attributes beyond a normal exception.
try:
litellm.completion(model=model, messages=messages, max_tokens=400)
except litellm.NotFoundError as error:
print(error.status_code) # the HTTP status
print(error.llm_provider) # which provider failed
print(error.message) # the provider's textCalling a model that does not exist
import litellm
litellm.suppress_debug_info = True
try:
litellm.completion(model="groq/openai/not-a-model", messages=[{"role": "user", "content": "hi"}], max_tokens=400)
except Exception as error:
print(type(error).__name__, error.status_code, error.llm_provider)NotFoundError 404 groq
The class is NotFoundError, with status 404 and the provider groq. Groq reported that the model does not exist, and LiteLLM named the failure the same way for every provider.
Calling with a bad API key on two providers
The loop below sends a made-up key to Groq and to Gemini. It passes the key with api_key=, as Providers and keys: the model string described.
import litellm
litellm.suppress_debug_info = True
messages = [{"role": "user", "content": "hi"}]
for model in ["groq/openai/gpt-oss-120b", "gemini/gemini-2.5-flash-lite"]:
try:
litellm.completion(model=model, messages=messages, max_tokens=400, api_key="wrong-key")
except Exception as error:
print(model, "->", type(error).__name__, error.status_code)groq/openai/gpt-oss-120b -> BadRequestError 401 gemini/gemini-2.5-flash-lite -> AuthenticationError 401
Seeing what each provider sent before LiteLLM mapped it
The next example sends the same made-up key straight to each provider with httpx, and no LiteLLM. It prints the HTTP status and the provider's own name for the error.
import httpx
groq = httpx.post(
"https://api.groq.com/openai/v1/chat/completions",
headers={"Authorization": "Bearer wrong-key"},
json={"model": "openai/gpt-oss-120b", "messages": [{"role": "user", "content": "hi"}]},
)
gemini = httpx.post(
"https://generativelanguage.googleapis.com/v1beta/models/gemini-2.5-flash-lite:generateContent",
headers={"x-goog-api-key": "wrong-key"},
json={"contents": [{"parts": [{"text": "hi"}]}]},
)
print("Groq ", groq.status_code, groq.json()["error"]["type"])
print("Gemini", gemini.status_code, gemini.json()["error"]["details"][0]["reason"])Groq 401 invalid_request_error Gemini 400 API_KEY_INVALID
Reading why the two providers raised different classes
- Groq sent HTTP 401, and LiteLLM raised
BadRequestError. Groq's body names its error typeinvalid_request_error. LiteLLM 1.105.0 reads the text of the error before it reads the status, and any error carrying that type becomes aBadRequestError. The exception keeps the 401 that Groq sent. - Gemini sent HTTP 400, and LiteLLM raised
AuthenticationError. The body saysAPI key not valid, and LiteLLM recognises that text as a bad key. It reports the status as 401, though Google sent 400. - The class depends on the provider's wording. It is not a rule that a bad key is an
AuthenticationError. What the two exceptions share isstatus_code, which is 401 on both. - One handler for both has to list both classes, or test
error.status_code == 401.
try:
litellm.completion(model=model, messages=messages, max_tokens=400)
except (litellm.AuthenticationError, litellm.BadRequestError) as error:
if error.status_code == 401: # a bad key, on either provider
print("check the API key")
else:
raiseWaiting too long for an answer
timeout is the number of seconds a call may wait. Past it, LiteLLM abandons the call and raises Timeout with status 408. A tiny timeout makes it happen so you can watch it.
import litellm
litellm.suppress_debug_info = True
try:
litellm.completion(model="groq/openai/gpt-oss-120b", messages=[{"role": "user", "content": "hi"}], max_tokens=400, timeout=0.001)
except litellm.Timeout as error:
print(type(error).__name__, error.status_code, error.llm_provider)Timeout 408 groq
Without a timeout a call waits as long as the provider takes. On a service that is a connection held open for as long as a provider is struggling.
Catching errors with the OpenAI exceptions
Every LiteLLM exception inherits from the matching class in the openai package, so code that already handles OpenAI's errors handles every provider's.
import openai
import litellm
litellm.suppress_debug_info = True
try:
litellm.completion(model="groq/openai/not-a-model", messages=[{"role": "user", "content": "hi"}], max_tokens=400)
except openai.NotFoundError as error:
print(type(error).__name__, isinstance(error, litellm.NotFoundError))NotFoundError True
The exception classes and their statuses
| Status | Class | Raised when |
|---|---|---|
| 400 | BadRequestError | The request is refused as invalid. A bad Groq key also lands here, with status 401. |
| 400 | UnsupportedParamsError | A parameter is not supported by the provider |
| 401 | AuthenticationError | The key is refused, in wording LiteLLM maps to this class, as Gemini's is |
| 404 | NotFoundError | The model does not exist |
| 408 | Timeout | The call took longer than timeout |
| 429 | RateLimitError | A rate limit was crossed |
| 503 | ServiceUnavailableError | The provider is down |
This is the list on the exception mapping page, restricted to the classes met in this part. Each class in the table except RateLimitError and ServiceUnavailableError was raised by a real call in this part. Those two need a provider that is limited or down, so they are not forced here. Retries: trying again when a provider refuses acts on them.
Where you use mapped exceptions
- Deciding what to retry. A 429 or a 5xx may work on a second try. A 400 or 401 fails the same way again.
- Showing the user a clear message for a timeout or a rate limit, and hiding the provider's text.
- Logging the provider with
error.llm_provider, so an incident names who failed.
AuthenticationError. On Groq it raises BadRequestError, and an except AuthenticationError clause misses it. Check error.status_code for 401, or test the provider you use.Related
- Previous: Tokens and cost
- Next: Callbacks: tracking every call
- Reference: Exception mapping in the LiteLLM docs
- Add a wrong
api_keyto a Gemini call and printerror.llm_provideranderror.message. - Change the unknown model to
"gemini/not-a-model"and read the class and status. - Set
timeout=30and run the timeout example again. It now answers normally.
Every expert started right here.