Applies to:
- Plan - Any
- Deployment - Any
- Use case - Troubleshoot OpenAI embedding authentication errors.
Summary
Embedding requests totext-embedding-3-small can return upstream 401 errors when the selected native OpenAI provider is configured with auth_format: "api_key". Set the provider’s authorization format to "bearer" and retry. Include x-bt-project-id when you need project-level providers. Changing the auth format resolves this misconfiguration. Adding routing headers alone does not.
What is happening
The client authenticates to the Gateway usingAuthorization: Bearer <BRAINTRUST_API_KEY>. The Gateway then uses the selected provider’s stored OpenAI key and auth_format to authenticate upstream. OpenAI expects bearer authentication, so auth_format: "api_key" can cause embedding requests to fail even when other OpenAI calls succeed. By default, the Gateway uses organization-level providers. Including x-bt-project-id makes that project’s providers available, with provider selection determined by the Gateway’s routing rules.
Fix or suggestion
Option 1: change provider auth_format to bearer
- Go to Settings > Models.
- Select the Organization or Project tab to match the provider’s scope, then open the OpenAI provider used by the failing request.
- On the Setup tab, expand More settings if it is collapsed, and select Form.
- Set Authorization header format to Bearer. If you authenticate with an OpenAI API key, keep API key selected as the authentication method.
- Click Save.
- If you need project-level providers, include
x-bt-project-idon embedding requests and retry.
auth_format from "api_key" to "bearer" in your existing provider configuration. Preserve its credentials, API base URL, and other settings. The following excerpts illustrate the change.
Before:
Option 2: verify headers and provider routing
- Confirm the request includes
Authorization: Bearer <BRAINTRUST_API_KEY>. - For troubleshooting, temporarily remove
x-bt-fallback-providersand other optional routing headers to simplify the request. Their presence alone does not establish the cause of a 401. - Confirm the selected provider’s
api_basematches the OpenAI endpoint you expect. - Organization-level providers do not require
x-bt-project-id. Include it when you need the Gateway to consider project-level providers.
How to confirm it worked
- A successful embedding request returns HTTP 200 and, with the default float encoding, an embedding vector in
data[0].embedding. - Check logs or request traces and confirm the retried embedding request returned a 200 status for the intended model and provider.
Notes
- To verify supported models, see Supported models.
- Keep API keys and secrets out of logs and UI screenshots. Replace actual keys with placeholders when sharing request examples.