BoundaryML/baml · error

baml.fetch_as: HTTP request failed: HTTP {status} Body: {bod

Error message

baml.fetch_as: HTTP request failed: HTTP {status}
Body: {body}

What it means

After baml.fetch_as sends its HTTP request, the runtime checks the response status. If it is a 4xx client error or 5xx server error, it fails with this error including the status code and the response body, rather than trying to parse the body into the target type.

Source

Thrown at engine/baml-runtime/src/async_vm_runtime.rs:700

                                                break 'res Err(anyhow::Error::from(e).context(
                                                    "baml.fetch_as: failed to send request",
                                                ));
                                            }
                                        };

                                        let status = res.status();

                                        let body = match res.text().await {
                                            Ok(body) => body,
                                            Err(e) => {
                                                break 'res Err(anyhow::Error::from(e).context(
                                                    "baml.fetch_as: failed to read response body",
                                                ));
                                            }
                                        };

                                        if status.is_client_error() || status.is_server_error() {
                                            break 'res Err(anyhow::anyhow!(
                                            "baml.fetch_as: HTTP request failed: HTTP {status}\nBody: {body}"
                                        ));
                                        }

                                        jsonish::from_str(
                                            &output_format,
                                            &parse_as_type,
                                            &body,
                                            true,
                                        )
                                        .context(
                                            "(jsonish) Failed parsing response of fetch_value call",
                                        )
                                    };

                                    let response_baml_value = response.map(|r| {
                                        ResponseBamlValue(
                                            BamlValueWithMeta::<Vec<Flag>>::from(r).map_meta(

View on GitHub (pinned to bd85ce9dee)

Solutions

1. Read the status and body in the error to identify the cause (auth, not-found, validation, server error)
2. Fix auth: supply correct API key/token in headers via the HttpRequest helper
3. Verify the URL path, query parameters and request body match the API contract
4. Handle retries for transient 5xx/429 with backoff

Example fix

// before (BAML)
let req = http.request("GET", "https://api.example.com/v1/items")
let res = baml.fetch_as(req, Item[])
// after (BAML)
let req = http.request("GET", "https://api.example.com/v1/items")
  .header("Authorization", "Bearer ${env.API_KEY}")
let res = baml.fetch_as(req, Item[])

// pre-check endpoint health in a wrapper
// if !endpoint_reachable(url) { skip fetch }

// catch and inspect status before deciding to retry
if err.contains("HTTP 4") { don't retry } else if err.contains("HTTP 5") || err.contains("429") { retry with backoff }

When it happens

Trigger: baml.fetch_as(url, Type) where the remote endpoint returns HTTP 4xx/5xx — e.g. wrong API path, missing/invalid auth headers, bad request body, or the server being down.

Common situations: Calling a REST API with an expired API key (401), a mistyped endpoint (404), invalid JSON payload (400), or rate limiting (429); server-side crashes returning 500.

Understand the failure class

Background: "API error: {status}" and "HTTP 401/403/404/429/5xx" errors: non-2xx HTTP responses explained — this error's family across 27 libraries.

Related errors

• baml.fetch_as: HTTP request failed: HTTP {} Body: {} at {:?}
• Failed to fetch media: {e:?}
• Failed to fetch: {url}
• Auth server returned {status}: {body}
• PostHog returned {status}

AI-assisted analysis of BoundaryML/baml@bd85ce9dee (2026-09-12). Data as JSON: /api/errors/ca598950a028ecd7. Report an issue: GitHub.