LiteLLMLiteLLM 1.105 · Python 3.10+
Dashboard
0%

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.

Four real provider errors and the LiteLLM exception each became. A Groq unknown model, HTTP 404, became NotFoundError. A Groq bad API key, HTTP 401 with type invalid_request_error, became BadRequestError. A Gemini bad API key, HTTP 400 with reason <code>API_KEY_INVALID</code>, became AuthenticationError with status 401. A Gemini unknown model, HTTP 404, became NotFoundError.

Syntax: catch a LiteLLM class from the litellm module. Every one carries three extra attributes beyond a normal exception.

python
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 text

Calling a model that does not exist

ExampleAn unknown Groq model
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)

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.

ExampleA bad key on Groq and on Gemini
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)

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.

ExampleA bad key as each provider reports it
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"])

Reading why the two providers raised different classes

  • Groq sent HTTP 401, and LiteLLM raised BadRequestError. Groq's body names its error type invalid_request_error. LiteLLM 1.105.0 reads the text of the error before it reads the status, and any error carrying that type becomes a BadRequestError. The exception keeps the 401 that Groq sent.
  • Gemini sent HTTP 400, and LiteLLM raised AuthenticationError. The body says API 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 is status_code, which is 401 on both.
  • One handler for both has to list both classes, or test error.status_code == 401.
python
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:
        raise

Waiting 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.

ExampleA timeout of one millisecond
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)

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.

ExampleCatching a LiteLLM error as an OpenAI error
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))

The exception classes and their statuses

StatusClassRaised when
400BadRequestErrorThe request is refused as invalid. A bad Groq key also lands here, with status 401.
400UnsupportedParamsErrorA parameter is not supported by the provider
401AuthenticationErrorThe key is refused, in wording LiteLLM maps to this class, as Gemini's is
404NotFoundErrorThe model does not exist
408TimeoutThe call took longer than timeout
429RateLimitErrorA rate limit was crossed
503ServiceUnavailableErrorThe 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.
Watch out. Do not assume a bad key raises 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.
Try it yourself
  • Add a wrong api_key to a Gemini call and print error.llm_provider and error.message.
  • Change the unknown model to "gemini/not-a-model" and read the class and status.
  • Set timeout=30 and run the timeout example again. It now answers normally.

Every expert started right here.