{"record":{"id":"e2aa2767a54872c0","repo":"BerriAI/litellm","slug":"azureexception-apierror-message","errorCode":null,"errorMessage":"AzureException APIError - {message}","messagePattern":"AzureException APIError - (.+?)","errorType":"exception","errorClass":"APIError","httpStatus":500,"severity":"error","filePath":"litellm/litellm_core_utils/exception_mapping_utils.py","lineNumber":2051,"sourceCode":"            )\n        elif original_exception.status_code == 503:\n            raise ServiceUnavailableError(\n                message=f\"AzureException ServiceUnavailableError - {message}\",\n                model=model,\n                llm_provider=\"azure\",\n                litellm_debug_info=extra_information,\n                response=getattr(original_exception, \"response\", None),\n            )\n        elif original_exception.status_code == 504:  # gateway timeout error\n            raise Timeout(\n                message=f\"AzureException Timeout - {message}\",\n                model=model,\n                litellm_debug_info=extra_information,\n                llm_provider=\"azure\",\n                exception_status_code=original_exception.status_code,\n            )\n        else:\n            raise APIError(\n                status_code=original_exception.status_code,\n                message=f\"AzureException APIError - {message}\",\n                llm_provider=\"azure\",\n                litellm_debug_info=extra_information,\n                model=model,\n                request=httpx.Request(method=\"POST\", url=\"https://openai.com/\"),\n            )\n    else:\n        # if no status code then it is an APIConnectionError: https://github.com/openai/openai-python#handling-errors\n        raise APIConnectionError(\n            message=f\"{exception_provider} APIConnectionError - {message}\\n{_redact_string(traceback.format_exc())}\",\n            llm_provider=\"azure\",\n            model=model,\n            litellm_debug_info=extra_information,\n            request=httpx.Request(method=\"POST\", url=\"https://openai.com/\"),\n        )\n\n","sourceCodeStart":2033,"sourceCodeEnd":2069,"githubUrl":"https://github.com/BerriAI/litellm/blob/77b7c6c40c0c5aa5fbcb1d6a1825ac39ca8829b8/litellm/litellm_core_utils/exception_mapping_utils.py#L2033-L2069","documentation":"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.","triggerScenarios":"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.","commonSituations":"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.","solutions":["Catch litellm.APIError and log e.status_code, e.message and litellm_debug_info to identify the real Azure error.","For 403: check Azure content filters, key permissions (RBAC 'Cognitive Services OpenAI User'), and subscription state.","Align your litellm version with the latest release so newly observed Azure status codes get specific mappings.","If the status is 5xx-like, retry with exponential backoff or route to a fallback deployment."],"exampleFix":"# before\nresp = litellm.completion(model=\"azure/dep\", messages=msgs)\n\n# after\ntry:\n    resp = litellm.completion(model=\"azure/dep\", messages=msgs)\nexcept litellm.APIError as e:\n    print(\"upstream status:\", e.status_code)\n    if e.status_code and e.status_code >= 500:\n        raise  # transient, retry upstream\n    raise","handlingStrategy":"try-catch","validationCode":null,"typeGuard":"def is_retryable_api_error(e: Exception) -> bool:\n    return isinstance(e, litellm.APIError) and getattr(e, \"status_code\", 0) is not None and e.status_code >= 500","tryCatchPattern":"try:\n    resp = litellm.completion(**kwargs)\nexcept litellm.APIError as e:\n    if e.status_code == 403:\n        handle_permissions_or_content_filter(e)\n    elif e.status_code >= 500:\n        retry_with_backoff()\n    else:\n        raise","preventionTips":["Log e.status_code and litellm_debug_info on every Azure APIError — the real cause is upstream's code.","Keep litellm current so new Azure statuses gain specific mappings.","Codify 403 handling: content filter and RBAC are the most common non-mapped statuses."],"tags":["azure","api-error","catch-all","status-code","litellm","exception-mapping"],"backgroundTag":"provider-api-error","analyzedSha":"77b7c6c40c0c5aa5fbcb1d6a1825ac39ca8829b8","analyzedAt":"2026-08-18T11:44:31.656Z","contentChangedAt":null,"schemaVersion":2},"datasetVersion":"2026-09-23T08:17:48.524Z"}