Relevant issues

Second of three PRs making basedpyright actually analyze the codebase's hottest functions. Across litellm/, basedpyright bails out with "Code is too complex to analyze" on exactly three functions, skipping their entire bodies: CustomStreamWrapper.chunk_creator (done in #30793), exception_type (this PR), and completion (litellm/main.py, still to come). Each is scoped on its own.

Linear ticket

N/A

Pre-Submission checklist

• I have added meaningful tests: two regression tests for the latent bug this refactor surfaced (the exception_type class-name local that two provider branches key on), plus one pinning the replicate 422 mapping after the dead-branch cleanup below; each fails when its target is broken and passes once it is restored, and the existing mapped suite exercises the dispatch across providers
• My PR passes all unit tests on make test-unit
• My PR's scope is as isolated as possible; it only restructures exception_type and its helpers in one module, plus the mapped test file
• I have requested a Greptile review and received a Confidence Score of at least 4/5

What and why

exception_type packed a ~20-branch per-provider if/elif dispatch, each branch heavy with nested status-code and error-string checks, into a single ~2,280-line body. That pushed it past basedpyright's code-flow complexity ceiling, so basedpyright emitted "Code is too complex to analyze" and skipped the whole function. Every type error on one of the hottest error-mapping paths was invisible and unguarded.

This extracts the dispatch into 18 typed helper functions, one per provider family, and leaves the common setup, the timeout and litellm_proxy special cases, the generic catch-all and the except handler in exception_type. The function drops well under the ceiling and basedpyright now type-checks it and every helper.

The dynamic provider exception is modelled with a small _ProviderHTTPException Protocol so the helpers read status_code/message/response without Any, which keeps the per-rule basedpyright budget green on the unchanged baseline; no ceiling moves. The per-branch exception_mapping_worked = True assignments become moot once each branch lives in its own helper: the except handler already re-raises litellm exceptions through its isinstance loop regardless of the flag, and the three raise original_exception sites already ran with the flag False, so the propagated exception is identical in every case.

Extracting the blocks surfaced a latent bug. Two branches, replicate's "ModelError" and cohere's "CohereConnectionError", key on type(original_exception).__name__, which the original code held in a local named exception_type that shadowed the function itself. That class-name value is now threaded into the helpers; without it the bare name resolves to the module-level function and the branch silently mismaps (or raises TypeError) into a generic APIConnectionError. The two new regression tests cover exactly these paths.

Extraction also surfaced a dead branch in the replicate status-code ladder: two identical status_code == 422 elif branches, where the second can never run because the elif chain exits on the first match. It was faithfully carried over from the pre-refactor function. This drops the unreachable duplicate and leaves the reachable branch that maps a replicate 422 to UnprocessableEntityError untouched; since the removed branch was dead, there is no behavior change. A third regression test pins that 422 mapping so the surviving branch can't be dropped or broken silently.

Screenshots / Proof of Fix

Before, on litellm_internal_staging, basedpyright refuses to analyze the function:

$ uv run basedpyright litellm/litellm_core_utils/exception_mapping_utils.py 2>&1 | grep "too complex"
  litellm/litellm_core_utils/exception_mapping_utils.py:247:5 - error: Code is too complex to analyze; reduce complexity by refactoring into subroutines or reducing conditional code paths (reportGeneralTypeIssues)

After this PR the bailout is gone and the per-rule budget gate passes on the unchanged budget:

$ uv run basedpyright litellm/litellm_core_utils/exception_mapping_utils.py 2>&1 | grep -c "too complex"
0

$ make lint-basedpyright
OK: every rule is within its basedpyright ceiling

$ git diff --stat basedpyright-code-budget.json
(no changes)

Behavioral proof against a live proxy hitting real provider APIs and spending real money. The refactored dispatch routes by provider, so this exercises two different helpers on real upstream errors plus a billed success, and confirms each maps to the correct litellm exception.

1. Start the proxy

python litellm/proxy/proxy_cli.py --config litellm/proxy/dev_config.yaml --detailed_debug --reload --use_v2_migration_resolver 2>&1 | tee litellm.log

2. Billed success through the shared path (the module is on every request; this confirms the happy path is intact)

curl -s http://localhost:4000/v1/chat/completions \
  -H "Authorization: Bearer sk-1234" -H "Content-Type: application/json" \
  -d '{"model":"anthropic-haiku-4-5","messages":[{"role":"user","content":"Reply with exactly: exception refactor intact"}]}'
# -> "exception refactor intact"   (proxy-computed spend $0.00005)

3. Real Anthropic context-window overflow, mapped by _map_anthropic_exception

# a >200k-token prompt to anthropic-haiku-4-5
# Anthropic returns 400 "prompt is too long: 207805 tokens > 200000 maximum"
HTTP status: 400
message: litellm.ContextWindowExceededError: litellm.BadRequestError: AnthropicError - prompt is too long: 207805 tokens > 200000 maximum

4. Real OpenAI bad request, mapped by _map_openai_exception

curl -s http://localhost:4000/v1/chat/completions \
  -H "Authorization: Bearer sk-1234" -H "Content-Type: application/json" \
  -d '{"model":"gpt-5.5","messages":[]}'
HTTP status: 400
type: invalid_request_error
message: litellm.BadRequestError: OpenAIException - Invalid 'messages': empty array. Expected an array with minimum length 1, but got an empty array instead.

The regression tests are also mutation-checked: passing the class-name as "" to the helpers (simulating broken threading) makes the replicate and cohere tests fail, and restoring the threading makes them pass; disabling the surviving 422 branch makes the new replicate 422 test fail.

Type

🧹 Refactoring

Changes

Extracts the per-provider dispatch out of exception_type into 18 typed helper functions plus a _ProviderHTTPException Protocol for the dynamic exception shape, restoring basedpyright analysis of the function and its helpers with no budget ceiling moved. Threads the exception class-name into the helpers so the replicate and cohere class-name branches keep working, drops the unreachable duplicate replicate 422 branch, and adds three regression tests for those paths. No behavior change to the propagated exceptions.