{"record":{"id":"977737e5c97022ac","repo":"BoundaryML/baml","slug":"llm-client-client-name-failed-with-status-code-status-code","errorCode":null,"errorMessage":"LLM client \"{client_name}\" failed with status code: {status_code}\\nMessage: {message}","messagePattern":"LLM client \"(.+?)\" failed with status code: (.+?)\\\\nMessage: (.+?)","errorType":"http","errorClass":"ExposedError::ClientHttpError","httpStatus":null,"severity":"error","filePath":"engine/baml-runtime/src/internal/llm_client/orchestrator/call.rs","lineNumber":148,"sourceCode":"                        message,\n                        raw_response,\n                        ..\n                    }) => {\n                        match code {\n                            // Timeout error\n                            crate::internal::llm_client::ErrorCode::Timeout => {\n                                Some(Err(anyhow::anyhow!(\n                                    crate::errors::ExposedError::TimeoutError {\n                                        client_name: client.clone(),\n                                        message: message.clone(),\n                                    }\n                                )))\n                            }\n                            // This is some internal BAML error, so handle it like any other error\n                            crate::internal::llm_client::ErrorCode::Other(2) => {\n                                Some(Err(anyhow::anyhow!(message.clone())))\n                            }\n                            _ => Some(Err(anyhow::anyhow!(\n                                crate::errors::ExposedError::ClientHttpError {\n                                    client_name: client.clone(),\n                                    message: message.clone(),\n                                    status_code: code.clone(),\n                                    detailed_message: message.clone(),\n                                    raw_response: raw_response.clone(),\n                                }\n                            ))),\n                        }\n                    }\n                    _ => None,\n                };\n\n                let sleep_duration = node.error_sleep_duration().cloned();\n                let result = (node.scope, response, parsed_response);\n\n                // Return None to signal success and break\n                if matches!(result.1, LLMResponse::Success(_)) {","sourceCodeStart":130,"sourceCodeEnd":166,"githubUrl":"https://github.com/BoundaryML/baml/blob/bd85ce9dee1463ff04d27efd20531013a4ff46c1/engine/baml-runtime/src/internal/llm_client/orchestrator/call.rs#L130-L166","documentation":"For any LLMFailure whose error code is neither Timeout nor Other(2), the orchestrator wraps the failure into ExposedError::ClientHttpError, exposing the client name, HTTP status code, detailed message, and the raw response body. This is BAML's standard way of propagating an HTTP error response from the model provider (4xx/5xx) to the caller.","triggerScenarios":"Calling a BAML function where the provider responds with a non-success HTTP status: 401/403 (bad key), 404 (bad model name), 429 (rate limit), 500 (provider outage), or a 400 (malformed request/parameters).","commonSituations":"Expired or wrong API key, model name not available on the account/region, exceeding rate limits or quota, invalid request options (temperature type errors, bad json_schema), provider-side incidents.","solutions":["Check status_code in the error: 401/403 -> fix API key/permissions; 429 -> backoff and reduce concurrency; 404/400 -> fix model name and options.","Inspect detailed_message/raw_response for the provider's own error body explaining the rejection.","Verify the api_key env var value and that the account has access to the requested model.","Add a retry_policy with exponential backoff and a fallback client in the BAML function's retry strategy.","Pin/adjust request options to what the provider version supports."],"exampleFix":"// before (clients.baml)\nfunction Extract(input: string) -> Output {\n  provider \"gpt4\"\n}\n// after - add retry + fallback for HTTP failures\nfunction Extract(input: string) -> Output {\n  provider \"gpt4\"\n  retry_policy RateLimitRetry\n}\nretry_policy RateLimitRetry {\n  max_retries 5\n  strategy { type exponential_backoff }\n}","handlingStrategy":"try-catch","validationCode":"// preflight: verify key present and model reachable\nimport os\nif not os.environ.get(\"OPENAI_API_KEY\"):\n    raise RuntimeError(\"OPENAI_API_KEY missing; would get 401 ClientHttpError\")","typeGuard":null,"tryCatchPattern":"// python\nfrom baml_py import BamlError, ClientHttpError\ntry:\n    result = b.ExtractDocs(text)\nexcept ClientHttpError as e:\n    code = e.status_code\n    if code == 429:\n        time.sleep(backoff); retry()\n    elif code in (401, 403):\n        alert(\"bad credentials\")\n    else:\n        log.error(\"provider http %s: %s\", code, e.raw_response)","preventionTips":["Preflight API keys and model access in CI before deploying.","Configure retry_policy with exponential backoff plus a fallback client.","Cap concurrency to stay under provider rate limits.","Log raw_response on failures to capture the provider's own explanation."],"tags":["http","llm","api","status-code"],"backgroundTag":"http-error-response","analyzedSha":"bd85ce9dee1463ff04d27efd20531013a4ff46c1","analyzedAt":"2026-09-12T03:38:25.718Z","contentChangedAt":"2026-09-12T03:38:25.718Z","schemaVersion":2},"datasetVersion":"2026-09-14T05:17:10.506Z"}