HTTP 421 errors with self-hosted data planes

Applies to:

Plan - Enterprise
Deployment - Self-hosted
Use case - API requests with custom data plane configurations

Summary Issue: API requests fail with HTTP 421 Client Error: Misdirected Request when making requests to https://api.braintrust.dev in self-hosted or enterprise deployments. Cause: Your organization uses a custom data plane URL, and the default API endpoint returns 421 when it detects this configuration. Resolution: Use your organization’s custom data plane API URL instead of the default endpoint.

Resolution Steps

Step 1: Find your custom API URL

Navigate to Settings → Data plane → API URL and copy the custom API URL displayed.

Step 2: Update your API requests

Replace https://api.braintrust.dev with your custom API URL in all requests.

response = requests.post(
    "https://your-custom-url.braintrust.dev/btql",  # Use your custom URL
    headers={
        "Authorization": f"Bearer {BRAINTRUST_API_KEY}",
        "Content-Type": "application/json"
    },
    json={"query": "..."}
)

Step 3: Verify the request succeeds

Test your API request to confirm it returns a successful response instead of the 421 error.

​Resolution Steps

​Step 1: Find your custom API URL

​Step 2: Update your API requests

​Step 3: Verify the request succeeds

Resolution Steps

Step 1: Find your custom API URL

Step 2: Update your API requests

Step 3: Verify the request succeeds