{"record":{"id":"f67425574d591298","repo":"BerriAI/litellm","slug":"apierror-exception-provider-error-str","errorCode":null,"errorMessage":"APIError: {exception_provider} - {error_str}","messagePattern":"APIError: (.+?) - (.+?)","errorType":"exception","errorClass":"APIError","httpStatus":null,"severity":"error","filePath":"litellm/litellm_core_utils/exception_mapping_utils.py","lineNumber":2145,"sourceCode":"            )\n        elif original_exception.status_code == 503:\n            raise ServiceUnavailableError(\n                message=f\"ServiceUnavailableError: {exception_provider} - {error_str}\",\n                model=model,\n                llm_provider=custom_llm_provider,\n                response=getattr(original_exception, \"response\", None),\n                litellm_debug_info=extra_information,\n            )\n        elif original_exception.status_code == 504:  # gateway timeout error\n            raise Timeout(\n                message=f\"Timeout Error: {exception_provider} - {error_str}\",\n                model=model,\n                llm_provider=custom_llm_provider,\n                litellm_debug_info=extra_information,\n                exception_status_code=original_exception.status_code,\n            )\n        else:\n            raise APIError(\n                status_code=original_exception.status_code,\n                message=f\"APIError: {exception_provider} - {error_str}\",\n                llm_provider=custom_llm_provider,\n                model=model,\n                request=getattr(original_exception, \"request\", None),\n                litellm_debug_info=extra_information,\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\"APIConnectionError: {exception_provider} - {error_str}\",\n            llm_provider=custom_llm_provider,\n            model=model,\n            litellm_debug_info=extra_information,\n            request=httpx.Request(method=\"POST\", url=\"https://api.openai.com/v1/\"),\n        )\n\n","sourceCodeStart":2127,"sourceCodeEnd":2163,"githubUrl":"https://github.com/BerriAI/litellm/blob/6c2dcb801bf2b75c18f1bb24140e7cf57465cc4d/litellm/litellm_core_utils/exception_mapping_utils.py#L2127-L2163","documentation":"This is LiteLLM's catch-all APIError for upstream HTTP exceptions that have a status code but do not match any specific mapping (400/401/403/429/503/504 etc.). The original status code is preserved on the raised exception, so inspect exception.status_code to understand the real failure.","triggerScenarios":"Any completion call whose upstream error has an unmapped status code — e.g. 402 (payment required), 409, 422, 499, 500, or non-standard codes returned by OpenAI-compatible providers.","commonSituations":"Billing issues (402), internal server errors (500) at third-party OpenAI-compatible endpoints, provider-specific validation codes, or new status codes not yet mapped by litellm.","solutions":["Catch APIError and branch on e.status_code to get the true cause.","For 5xx codes, retry with backoff; for 4xx codes, fix the request/billing/config.","Print the full message — it embeds the provider name and the original error string.","Check the provider's dashboard/logs for the corresponding request."],"exampleFix":"# before\nresp = litellm.completion(model=..., messages=msgs)\n\n# after\ntry:\n    resp = litellm.completion(model=..., messages=msgs)\nexcept litellm.APIError as e:\n    if e.status_code and e.status_code >= 500:\n        raise  # transient, retry upstream\n    raise","handlingStrategy":"try-catch","validationCode":null,"typeGuard":null,"tryCatchPattern":"try {\n  await litellm.completion(...);\n} catch (e) {\n  if (e instanceof litellm.APIError) {\n    const sc = e.status_code;\n    if (sc >= 500) { /* retry */ } else { /* fix request/billing, do not retry */ }\n  }\n}","preventionTips":["Always branch on e.status_code rather than the message text.","Treat 4xx APIError as permanent and 5xx as retryable.","Log the full message once — it embeds provider and upstream error string."],"tags":["api-error","catch-all","http-status","provider"],"backgroundTag":null,"analyzedSha":"6c2dcb801bf2b75c18f1bb24140e7cf57465cc4d","analyzedAt":"2026-08-15T07:12:03.035Z","schemaVersion":2},"datasetVersion":"2026-08-15T22:17:37.221Z"}