BerriAI/litellm · error · APIError

AzureException APIError

Error message

AzureException APIError - {message}

What it means

This is the catch-all branch of _map_azure_exception: any Azure error whose status_code is not 400/401/404/408/422/429/500/503/504 is re-raised as litellm.APIError with the original status code and the 'AzureException APIError' prefix. It preserves the upstream status_code, model, and litellm_debug_info so callers can branch on it.

Solutions

  1. Catch litellm.APIError and log e.status_code, e.message and litellm_debug_info to identify the real Azure error.
  2. For 403: check Azure content filters, key permissions (RBAC 'Cognitive Services OpenAI User'), and subscription state.
  3. Align your litellm version with the latest release so newly observed Azure status codes get specific mappings.
  4. If the status is 5xx-like, retry with exponential backoff or route to a fallback deployment.

Example fix

# before
resp = litellm.completion(model="azure/dep", messages=msgs)

# after
try:
    resp = litellm.completion(model="azure/dep", messages=msgs)
except litellm.APIError as e:
    print("upstream status:", e.status_code)
    if e.status_code and e.status_code >= 500:
        raise  # transient, retry upstream
    raise
Defensive patterns

Strategy: try-catch

Type guard

def is_retryable_api_error(e: Exception) -> bool:
    return isinstance(e, litellm.APIError) and getattr(e, "status_code", 0) is not None and e.status_code >= 500

Try / catch

try:
    resp = litellm.completion(**kwargs)
except litellm.APIError as e:
    if e.status_code == 403:
        handle_permissions_or_content_filter(e)
    elif e.status_code >= 500:
        retry_with_backoff()
    else:
        raise

Prevention

When it happens

Trigger: An Azure OpenAI call returning an uncommon HTTP status, e.g. 403 (content filter / quota), 409, 418, or 5xx values other than 500/503/504. Because the status is preserved, inspect exception.status_code to see the real Azure response.

Common situations: Azure content-filter blocks (403) or RBAC/Key permission problems; new Azure error codes not yet modeled by litellm; CORS/policy gateways between client and Azure returning unusual codes; partial outages returning 500-variant codes.

Related errors

AI-assisted analysis of BerriAI/litellm@77b7c6c40c (2026-08-18). Data as JSON: /api/errors/e2aa2767a54872c0. Report an issue: GitHub.

Appendix: source

Thrown at litellm/litellm_core_utils/exception_mapping_utils.py:2051

            )
        elif original_exception.status_code == 503:
            raise ServiceUnavailableError(
                message=f"AzureException ServiceUnavailableError - {message}",
                model=model,
                llm_provider="azure",
                litellm_debug_info=extra_information,
                response=getattr(original_exception, "response", None),
            )
        elif original_exception.status_code == 504:  # gateway timeout error
            raise Timeout(
                message=f"AzureException Timeout - {message}",
                model=model,
                litellm_debug_info=extra_information,
                llm_provider="azure",
                exception_status_code=original_exception.status_code,
            )
        else:
            raise APIError(
                status_code=original_exception.status_code,
                message=f"AzureException APIError - {message}",
                llm_provider="azure",
                litellm_debug_info=extra_information,
                model=model,
                request=httpx.Request(method="POST", url="https://openai.com/"),
            )
    else:
        # if no status code then it is an APIConnectionError: https://github.com/openai/openai-python#handling-errors
        raise APIConnectionError(
            message=f"{exception_provider} APIConnectionError - {message}\n{_redact_string(traceback.format_exc())}",
            llm_provider="azure",
            model=model,
            litellm_debug_info=extra_information,
            request=httpx.Request(method="POST", url="https://openai.com/"),
        )

View on GitHub (pinned to 77b7c6c40c)