Skip to main content
Most BYOK failures are configuration problems: the credential is shaped wrong for the provider, the underlying account lacks a permission, or fallback is masking a broken key. See BYOK for the full setup reference.
BYOK errors carry their own codes, so you can tell a provider-key failure from an rsk_ key failure:A 401 upstream_auth_error means your provider key was rejected. A plain 401 unauthorized is your rsk_ key.

​
401 — provider key invalid or revoked

The provider rejected the credential Mesh forwarded.
  • The key was rotated, revoked, or copied with a typo / trailing whitespace.
  • For Bedrock API keys, the key is tied to a specific AWS region — a key issued for one region won’t work for a model served from another.
  • Re-enter the key in the dashboard and confirm it’s active in the provider console.

​
401 permission_denied — key is valid but lacks permission for the model

Authentication worked, but the account isn’t authorized for that model or action (provider_code permission_denied or account_not_entitled).
  • AWS Bedrock — the IAM user/role is missing the required actions. Attach bedrock:InvokeModel, bedrock:InvokeModelWithResponseStream, and bedrock:ListFoundationModels.
  • Google Vertex AI — the service account needs the Vertex AI User role (roles/aiplatform.user) or at least aiplatform.endpoints.predict.
  • The model may not be enabled/available in your provider account or region.

​
Wrong credential shape (Bedrock / Vertex)

Each provider expects a specific format:
  • OpenAI — just the API key string.
  • Anthropic, Arcee, Cerebras, Cohere, DeepSeek, Fireworks, Flatkey, Moonshot, Parasail, Perplexity, Qwen, Sarvam: the API key string only.
  • AWS Bedrock: either a Bedrock API key or IAM credentials. Registering either needs credential_type, region and team_id; credential_type must match the contents: iam_credentials (with access_key_id, secret_access_key) vs bedrock_api_key.
  • Google Vertex AI — the full service-account JSON. region is optional and defaults to "global"; set it if your model is region-specific.
A mismatched credential_type or a missing region is a frequent cause of silent failures.

​
429 — rate limited on your own provider account

This is your provider’s rate limit, not Mesh’s. Requests-per-minute and token limits are governed by your OpenAI / AWS / Google account.
  • Raise the quota in the provider console, or slow down.
  • With fallback enabled, Mesh retries on platform credentials — so you may see success and a hidden fallback (see below).

​
Fallback masks a broken key (or a disabled fallback hard-fails)

By default, if your BYOK key fails, Mesh falls back to platform credentials and the request still succeeds — billed to your Mesh balance, not your provider. A key that’s been broken for weeks can go unnoticed this way.
  • To verify a key actually works, temporarily set the key to Exclusive Use (fallback disabled) and watch for failures.
  • With Exclusive Use on, a key failure fails the request with the provider’s error from the table above (for example 401 upstream_auth_error or 429 upstream_rate_limit_error). If routing would otherwise move the request to another provider on Mesh’s keys, you get 403 byok_fallback_disabled instead. There is no safety net. Expected behavior, not a bug. Don’t retry it unchanged: fix the key.

​
403 byok_model_not_allowed, or a model not using your key

Your key has an Allowed models list, and the requested model is not on it.
  • With fallback on, the model is served on Mesh’s credentials and billed to your Mesh balance. Nothing fails. The signs are X-BYOK-Used: false on chat completions, Responses and embeddings, and the credential shown in Dashboard → Logs.
  • With Exclusive Use on, the request returns 403 byok_model_not_allowed and nothing reaches the provider.
Add the model, or its brand wildcard such as openai/*, to the key’s Allowed models, or clear the list to let the key serve every model.

​
Unexpected BYOK charges

  • A 5% platform fee applies to BYOK requests, charged on the request’s cost at Mesh’s list prices, not on what your provider billed you. The first 1,000,000 tokens each month, audio tokens included, are fee-free.
  • If fallback fired, those tokens were billed to your Mesh balance at platform rates, not your provider account — check Dashboard → Logs to see which credential served each request.
  • A model outside the key’s Allowed models list is billed the same way, to your Mesh balance (see above).

​
Still stuck?

Check Dashboard → Logs for the exact provider error, then see the Mesh API error reference or email contact@meshapi.ai.