error-handling

name	error-handling
description	LiteLLM-RS Error Handling Architecture. Covers two-tier error hierarchy, ProviderError factory methods, HTTP status mapping, retry logic, and error context preservation. Use when designing error types or enums, creating ProviderError instances via factory methods, mapping HTTP statuses to typed errors, deciding retryability and backoff, or preserving error context.

Error Handling Architecture Guide

Two-Tier Error Hierarchy

LiteLLM-RS uses a two-tier error architecture spanning its provider catalog:

┌────────────────────────────────────────────────────────┐
│                    Gateway Layer                        │
│  LiteLLMError (core/types/errors/litellm.rs)          │
│  - Type alias for GatewayError                          │
│    (src/utils/error/gateway_error/types.rs)             │
│  - 18 variants for gateway-level errors                 │
└────────────────────────────────────────────────────────┘
                          ↓
┌────────────────────────────────────────────────────────┐
│                   Provider Layer                        │
│  ProviderError                                          │
│  (src/core/providers/unified_provider_error.rs;        │
│   exported as core::providers::ProviderError)           │
│  - 24 variants for provider-specific errors            │
│  - Each variant includes provider: &'static str        │
│  - Rich factory methods for error creation             │
└────────────────────────────────────────────────────────┘

---

HTTP Status Mapping

Standard Mapping Pattern

Most providers share one canonical status-to-error mapping, default_http_error_mapper in src/core/providers/unified_provider_http_mapping.rs:

pub fn default_http_error_mapper(
    provider: &'static str,
    status_code: ,
    response_body: &,
)  ProviderError {
     status_code {
         => {
              = (response_body)
                .(|| response_body.());
            ProviderError::(provider, message)
        }
         => ProviderError::(provider, ),
         => ProviderError::(provider, ),
         => ProviderError::(provider, ),
         => {
              =
                crate::core::providers::shared::(response_body);
            ProviderError::(provider, retry_after)
        }
        ..= => ProviderError::(provider, status_code, response_body),
        _ => ProviderError::(provider, status_code, response_body),
    }
}