{"record":{"id":"7b9d92e38dbc446a","repo":"BoundaryML/baml","slug":"bamlerror-bamlclienterror-bamlclienthttperror-message","errorCode":null,"errorMessage":"BamlError: BamlClientError: BamlClientHttpError: {message}","messagePattern":"BamlError: BamlClientError: BamlClientHttpError: (.+?)","errorType":"exception","errorClass":"BamlClientHttpError","httpStatus":null,"severity":"error","filePath":"engine/language_client_typescript/src/errors.rs","lineNumber":187,"sourceCode":"    napi::Error::new(napi::Status::GenericFailure, error_json.to_string())\n}\n\nfn throw_baml_client_http_error(\n    client_name: &str,\n    message: &str,\n    status_code: &ErrorCode,\n    detailed_message: Option<&str>,\n    raw_response: Option<&str>,\n) -> napi::Error {\n    let error_json = serde_json::json!({\n        \"type\": \"BamlClientHttpError\",\n        \"client_name\": client_name,\n        \"message\": format!(\"BamlError: BamlClientError: BamlClientHttpError: {}\", message),\n        \"status_code\": status_code.to_u16(),\n        \"detailed_message\": detailed_message,\n        \"raw_response\": raw_response,\n    });\n    napi::Error::new(napi::Status::GenericFailure, error_json.to_string())\n}\n\nfn throw_baml_abort_error(detailed_message: Option<&str>) -> napi::Error {\n    let error_json = serde_json::json!({\n        \"type\": \"BamlAbortError\",\n        \"detailed_message\": detailed_message,\n    });\n    napi::Error::new(napi::Status::GenericFailure, error_json.to_string())\n}\n\nfn throw_baml_timeout_error(client_name: &str, message: &str) -> napi::Error {\n    let error_json = serde_json::json!({\n        \"type\": \"BamlTimeoutError\",\n        \"client_name\": client_name,\n        \"message\": format!(\"BamlError: BamlClientError: BamlTimeoutError: {}\", message),\n    });\n    napi::Error::new(napi::Status::GenericFailure, error_json.to_string())\n}","sourceCodeStart":169,"sourceCodeEnd":205,"githubUrl":"https://github.com/BoundaryML/baml/blob/bd85ce9dee1463ff04d27efd20531013a4ff46c1/engine/language_client_typescript/src/errors.rs#L169-L205","documentation":"N-API error factory in the TypeScript client: wraps a runtime-side HTTP client failure into a structured BamlClientHttpError, embedding the status code, optional detailed message, and raw response into a JSON payload thrown to JS. The stringified message follows the BamlError: BamlClientError: BamlClientHttpError: chain used by the TS error-classification logic; from_anyhow_error routes qualifying anyhow errors here.","triggerScenarios":"Provider responds with 4xx/5xx during a BAML call and no retry policy recovers it — e.g. 401 invalid API key, 404 bad model name, 429 rate limit, 500 provider outage.","commonSituations":"Expired or missing API keys, wrong base_url, model names that don't exist for the account, quota exhaustion, provider downtime.","solutions":["Read status_code and raw_response in the error payload to identify the cause","401/403: fix the API key / credentials in client options","429: add or strengthen a retry_policy with backoff, or reduce request rate","Check provider status page and correct model/base_url in baml_src config"],"exampleFix":"// before\nclient GPT4 { provider openai options { api_key env.OPENAI_KEY_WRONG } }\n// after\nclient GPT4 {\n  provider openai\n  options { api_key env.OPENAI_API_KEY }\n  retry_policy Exponential\n}","handlingStrategy":"retry","validationCode":"if (!process.env[clientApiKeyEnvVar]) throw new Error(`Missing API key env var ${clientApiKeyEnvVar} for BAML client`);","typeGuard":"const isBamlHttpError = (e: unknown): boolean => String(e).includes('BamlClientHttpError');","tryCatchPattern":"try {\n  return await b.MyFunction(args);\n} catch (e) {\n  if (isBamlHttpError(e)) {\n    const detail = JSON.parse(String(e).replace(/^[^{]*/, ''));\n    if (detail.status_code === 429) await sleep(2000);\n    return await b.MyFunction(args); // safe retry for 429/5xx\n  }\n  throw e;\n}","preventionTips":["Configure retry_policy with exponential backoff in baml_src","Verify API keys and base_url per environment","Match model names to those available on your provider account","Handle 429 with rate limiting on your side","Alert on provider 5xx to detect outages"],"tags":["http","llm","api","typescript"],"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"}