`litellm.RateLimitError` — LiteLLM mapped a provider error to its 429 class

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

(The error as str(e) gives it when it comes from LiteLLM’s two generic raises 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.RateLimitError: .)

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 RateLimitError when a rate-limit test on the error text and the status code matches, when the provider’s exception carries status code 429 in the generic branch, and in a number of provider-specific branches on status 429, on status 402, on a status from 500 to 599 with a 429 code in the error body, on a phrase in the error text, or on the name of the original exception’s type, 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 RateLimitError(openai.RateLimitError):, in litellm/exceptions.py — a subclass of the OpenAI SDK’s own RateLimitError. Its constructor prefixes the message with litellm.RateLimitError: , sets self.status_code = 429 whatever the raise passed, and sets e.category to "vendor_rate_limit" unless the raise passes another category.

Where: exception_type in litellm_core_utils/exception_mapping_utils.py, which completion() raises from its except block; that file has 24 raise RateLimitError( statements, listed below, and one raise that builds a LiteLLM class from its name for the litellm_proxy provider. None of the 24 passes a category (our reading).

What to check: the provider’s own text at the end of the message, which says which limit was hit, e.llm_provider and e.model for which deployment it was, and, when the raise passed the provider’s response, its headers on e.response.headers — not on e.headers — before you decide how long to back off (our reading).

The two generic raises

In litellm/litellm_core_utils/exception_mapping_utils.py, inside _map_openai_exception (defined at line 275), the chain of tests opens at lines 307–311:

if ExceptionCheckers.is_error_str_rate_limit( error_str, status_code=getattr(original_exception, "status_code", None) ): raise RateLimitError( message=f"RateLimitError: {exception_provider} - {message}",

The raise passes model=model,, llm_provider=custom_llm_provider,, response=response, and body=getattr(original_exception, "body", None), (lines 312–315) — no litellm_debug_info. The test is a static method of class ExceptionCheckers: (line 39) in the same file; is_error_str_rate_limit (line 45) returns False when the error text is not a string (lines 59–60), and True when the text contains a standalone 429 and the status code is not an int or is 429, line 64:

if re.search(r"\b429\b", error_str) and (not isinstance(status_code, int) or status_code == 429):

or, whatever the status code, when the lower-cased text matches rate[\s_\-]*limit (line 70) or contains service tier capacity exceeded (line 76, under a comment that Mistral returns it); otherwise False (line 79). So a provider response with status 400 whose text says “rate limit” is raised as this class (our reading; the docstring, lines 51–54, says the phrase branches stay ungated).

When that test did not match, the second generic raise is at lines 464–466:

elif original_exception.status_code == 429: raise RateLimitError( message=f"RateLimitError: {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. So this raise runs when the original exception has a status_code attribute equal to 429 and none of the earlier branches of that chain (lines 307–421) matched (our reading). It passes model, llm_provider, response, litellm_debug_info=extra_information, and body (lines 467–471). In both raises response is what _litellm_proxy_response returns for the original exception (line 285); 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 RateLimitError( finds raise RateLimitError( at lines 310, 393, 465, 605, 672, 707, 766, 831, 944, 1010, 1118, 1237, 1259, 1327, 1454, 1511, 1539, 1609, 1685, 1784, 1846, 2088, 2190 and 2291, and no other construction of the class by that name. Besides lines 310 and 465:

OpenAI-style, on a phrase — line 393, under elif "Request too large" in error_str: (line 392) in the same chain, with the generic message form.
Anthropic — in _map_anthropic_exception, line 605, under elif original_exception.status_code == 429: (line 604) inside if hasattr(original_exception, "status_code"): (line 571), with the message f"AnthropicException - {error_str}" (line 606) and no response.
Replicate — in _map_replicate_exception: line 672, under elif "Request was throttled" in error_str: (line 671), and line 707, under elif original_exception.status_code == 429: (line 706) inside elif hasattr(original_exception, "status_code"): (line 678).
OpenAI-like providers — in _map_openai_like_exception: line 766, under elif "token_quota_reached" in error_str: (line 765), and line 831, under elif original_exception.status_code == 429: (line 830) inside elif hasattr(original_exception, "status_code"): (line 784); line 831 passes no response.
Bedrock — in _map_bedrock_exception: line 944, under elif "throttlingException" in error_str or "ThrottlingException" in error_str: (line 943), and line 1010, under elif original_exception.status_code == 429: (line 1009) inside elif hasattr(original_exception, "status_code"): (line 964).
SageMaker — in _map_sagemaker_exception, line 1118, under elif original_exception.status_code == 429: (line 1117) inside elif hasattr(original_exception, "status_code"): (line 1070).
Vertex AI and Gemini — in _map_vertex_exception: line 1237, under an elif (lines 1230–1236) testing the error text for 429 Quota exceeded, Quota exceeded for, Resource exhausted, IndexError: list index out of range or a 429 Unable to submit request phrase; line 1259, under an elif (lines 1250–1254) for an int status from 500 to 599 whose error body code is 429; and line 1327, under if original_exception.status_code == 429: (line 1326) inside if hasattr(original_exception, "status_code"): (line 1279). All three messages already begin litellm.RateLimitError: (lines 1238, 1260, 1328), so str(e) carries that prefix twice (our reading), and all three pass a new httpx.Response with status 429 and a stub request instead of the provider’s response.
Cohere — in _map_cohere_exception, line 1454, under an elif (lines 1451–1453) testing "CohereConnectionError" in exception_type, the name of the original exception’s type, not its text or status.
Hugging Face — in _map_huggingface_exception: line 1511, under elif "Rate limit reached" in error_str: (line 1510), with the error text alone as the message (line 1512), and line 1539, under elif original_exception.status_code == 429: (line 1538) inside if hasattr(original_exception, "status_code"): (line 1517).
AI21 — line 1609, under status 429 (line 1608) inside if hasattr(original_exception, "status_code"): (line 1587).
NLP Cloud — line 1685, under elif original_exception.status_code == 429 or original_exception.status_code == 402: (line 1684).
Together AI — line 1784, under status 429 (line 1783) inside if hasattr(original_exception, "status_code"): (line 1769).
Aleph Alpha — line 1846, under status 429 (line 1845) inside elif hasattr(original_exception, "status_code"): (line 1830).
Azure — in _map_azure_exception, line 2088, under status 429 (line 2087) inside elif hasattr(original_exception, "status_code"): (line 2046), with the message f"AzureException RateLimitError - {message}" (line 2089).
OpenRouter — in _map_openrouter_exception, line 2190, under status 429 (line 2189) inside if hasattr(original_exception, "status_code"): (line 2149), with the message f"RateLimitError: {exception_provider} - {error_str}" (line 2191). 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 2291, in _map_exception_by_status, described in the next section.
The litellm_proxy provider — for that provider exception_type first calls extract_and_raise_litellm_exception (lines 2448–2457), which finds the first match of litellm\.\w+Error in the error text (lines 232–233), looks the name up with getattr(litellm, exception_name, None) (line 237) and raises it with the whole error text as the message (lines 240–245). When the proxy’s error text names litellm.RateLimitError first, that raises this class (our inference: we did not fetch the package’s __init__.py), and str(e) then carries the prefix twice (our reading).

The phrase, Cohere, NLP Cloud 402 and Vertex AI 5xx branches and the ungated phrase tests in the generic chain do not test for status 429, so the class does not by itself tell you the provider sent 429 (our reading).

The fallback for status 429

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 429: (line 2290), raises this class at line 2291. 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 RateLimitError:, so str(e) reads litellm.RateLimitError: <Provider>Exception - <error text> (our reading, our placeholders).

Every raise above happens inside the try: at line 2373 (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 RateLimitError (exceptions.py line 978); 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’s own limiters.

The class

In litellm/exceptions.py, class RateLimitError(openai.RateLimitError): is at line 442. Its docstring (lines 443–453) calls it the “Unified rate-limit error” and says that rate-limit conditions from an upstream provider, a vendor batch endpoint, or one of LiteLLM’s own proxy-side limiters are raised as this class, with category telling them apart. Its constructor takes message, llm_provider, model and optional response, litellm_debug_info, max_retries, num_retries, category, rate_limit_type, headers, detail and body (lines 455–469), with category: str | RateLimitErrorCategory = (RateLimitErrorCategory.VENDOR_RATE_LIMIT), (line 464), then sets, lines 470–471:

self.status_code = 429 self.message = f"litellm.RateLimitError: {message}"

Lines 472–476 store llm_provider, model, litellm_debug_info, max_retries and num_retries as passed; line 477 stores category as its string value; lines 481–483 store rate_limit_type the same way. self.headers is built only from the headers= argument, else None (line 498); the comment above it (lines 488–496) says vendor response headers are deliberately not copied there and stay on e.response.headers. self.detail is detail or the message (line 501). Lines 502–510 build self.response as a new httpx.Response with status 429, the headers and the content of the response argument when one was passed, and a stub request to url=" https://cloud.google.com/vertex-ai/",; lines 511–513 pass self.message, response=self.response, body=body to the parent; and only then lines 514–515 set self.code = "429" and self.type = "throttling_error". Its __str__ (lines 517–523) and __repr__ (lines 525–531) 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 categories are an enum, RateLimitErrorCategory (line 24): vendor_rate_limit, vendor_batch_rate_limit, litellm_rate_limit and litellm_batch_rate_limit (lines 41–50), whose docstrings describe the first as “The upstream LLM provider returned a rate-limit response” (line 42) and the third as LiteLLM’s own rate limiter blocking the request (line 48). No raise in exception_mapping_utils.py passes category=, rate_limit_type= or headers=, so an error mapped there has e.category "vendor_rate_limit", e.rate_limit_type None and e.headers None — including the litellm_proxy path, whatever the proxy’s text says (our reading, from a grep of that file).

The parent, in the OpenAI Python SDK at v1.109.1 (the version we read; yours may differ), is class RateLimitError(APIStatusError): in src/openai/_exceptions.py (line 128). APIStatusError.__init__ (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 from the body when it is a dict and to None otherwise. Because LiteLLM sets code and type after that call, e.code is "429" and e.type "throttling_error" whatever the body held; e.param comes from the body (our reading, at that SDK version).

What it looks like in the field

In existence-master/Sentient#280, titled Chat shows the raw LiteLLM error when a cloud model hits a rate or credit limit, the reporter quotes an OpenRouter error from their app’s chat: litellm.RateLimitError: RateLimitError: OpenrouterException - {"error":{"message":"Rate limit exceeded: free-models-per-day. That has the doubled shape of lines 311, 466 and 2191 (our reading).

In FacundoSu1986/Sky-Claw#678, a report in Spanish about two Qodo Merge review workflows calling OpenRouter free models, the log reads litellm.RateLimitError: OpenrouterException - {"error":{"message": followed by a free-models-per-day limit text with code 429. That has one RateLimitError:, the shape of the fallback message at line 2256; the issue body we read gives no LiteLLM version, so we do not say which site raised it (our reading).

What the caller sees and can read

str(e) and e.message — litellm.RateLimitError: followed by the message the raise passed (line 471); str(e) adds the retry notes when those counts are non-zero (lines 517–523).
e.status_code — 429, set at line 470 for every raise, including the phrase branches, NLP Cloud’s 402 and Vertex AI’s 5xx branch. It does not tell you what the provider returned (our reading).
e.response — the httpx.Response built at lines 502–510: status 429, the headers and content of whatever response the raise passed, and a stub request (our reading). The Anthropic (line 605) and OpenAI-like (line 831) sites pass no response, and the Vertex AI sites pass one without provider headers or content, so there it has none (our reading).
e.headers — None from every site in the mapping file (our reading, above); provider headers such as a retry hint, when there are any, are on e.response.headers and e.litellm_response_headers.
e.category, e.rate_limit_type — "vendor_rate_limit" and None from that file (our reading, above).
e.llm_provider, e.model — what the raise passed (lines 472–473); at lines 310, 393 and 465 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, Bedrock (line 944), Cohere, Hugging Face, AI21, NLP Cloud, Together AI, Aleph Alpha and Azure sites pass a fixed provider name.
e.litellm_debug_info — what the raise passed (line 474). Lines 393, 465, 831, 1010, 1118, 1237, 1259, 1327, 2088, 2190 and 2291 pass extra_information; the others pass nothing, so it is None, the default at line 461 (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.code, e.type — "429" and "throttling_error" (lines 514–515).
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 which limit was hit: a 429 from the provider, a rate-limit phrase in a response with another status, a Vertex AI quota phrase, NLP Cloud’s 402, or a 429 wrapped in a 5xx (our reading).
Catch the class, not the status. Test isinstance(e, RateLimitError); e.status_code is 429 on every instance, so it cannot tell you what the provider sent (our reading, from line 470).
Do not expect e.category to separate a provider limit from a LiteLLM limit for errors mapped by exception_type: no raise there passes one, so it is "vendor_rate_limit", including for a proxy’s error relayed to the SDK (our reading). Other values come only from code that passes category=, which we did not trace.
Look for a retry hint on e.response.headers or e.litellm_response_headers, not e.headers (lines 488–498), and read whether the provider’s text names a per-day limit, as both field reports do, before you choose how long to wait (our reading).
Retry with backoff when the text points at a short window. 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, and it does not read any retry header (our reading). We say nothing here about any provider’s quotas.

from litellm import completion from litellm.exceptions import RateLimitError def call(model: str, messages: list[dict]): # Our sketch: show what LiteLLM attached when it mapped the error to its 429 class. try: return completion(model=model, messages=messages) except RateLimitError as e: print("provider:", e.llm_provider, "model:", e.model) print("category:", e.category, "limit type:", e.rate_limit_type) print("retry-after:", e.response.headers.get("retry-after")) print(e.message) raise

(Our sketch, not library code, and not run against your version. It re-raises: whether and when 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.RateLimitError is LiteLLM’s subclass of openai.RateLimitError, raised by exception_type — in the generic OpenAI-style branch when a rate-limit test on the error text and the status code matches, on a Request too large phrase, or when the provider’s exception has status_code 429 and matched no earlier test; in Anthropic, Replicate, OpenAI-like, Bedrock, SageMaker, Vertex AI, Hugging Face, AI21, Together AI, Aleph Alpha, Azure and OpenRouter branches on status 429; in NLP Cloud on 429 or 402; in Replicate, OpenAI-like, Bedrock, Vertex AI and Hugging Face branches on phrases; in Vertex AI on a 5xx with a 429 body code; in Cohere on the exception’s type name; in the status fallback for a 429; and, for litellm_proxy, when the proxy’s text names it. str(e) starts litellm.RateLimitError: , e.status_code is always 429 and, from that file, e.category is "vendor_rate_limit". Read the provider’s text and e.response.headers before you retry.

Nearby

litellm.ServiceUnavailableError — also from LiteLLM’s exception_type, but its object carries status_code 503 and the generic branch raises it for a provider status of 503; this one carries 429 and the generic branch raises it for 429 or a matching rate-limit test.
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 429.
overloaded_error — the Claude API’s own HTTP 529 error; LiteLLM’s Anthropic branch raises litellm.InternalServerError, not this class, for overloaded_error or Overloaded in the error text or for status 500 or 529 (lines 547 and 610), and this class for status 429 when no earlier test matched (line 604).

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.RateLimitError — LiteLLM mapped a provider error to its 429 class