Skip to main content
Applies to:
  • Plan - Any
  • Deployment - Any
  • Use case - Troubleshoot OpenAI embedding authentication errors.

Summary

Embedding requests to text-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 using Authorization: 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

  1. Go to Settings > Models.
  2. Select the Organization or Project tab to match the provider’s scope, then open the OpenAI provider used by the failing request.
  3. On the Setup tab, expand More settings if it is collapsed, and select Form.
  4. Set Authorization header format to Bearer. If you authenticate with an OpenAI API key, keep API key selected as the authentication method.
  5. Click Save.
  6. If you need project-level providers, include x-bt-project-id on embedding requests and retry.
If you use Raw instead of Form, change only 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:
After:
Example embedding request through the Gateway. Replace the project ID with your own, and include that header when you need project-level providers.

Option 2: verify headers and provider routing

  1. Confirm the request includes Authorization: Bearer <BRAINTRUST_API_KEY>.
  2. For troubleshooting, temporarily remove x-bt-fallback-providers and other optional routing headers to simplify the request. Their presence alone does not establish the cause of a 401.
  3. Confirm the selected provider’s api_base matches the OpenAI endpoint you expect.
  4. 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.