How do I troubleshoot AI Gateway errors?
| Symptom | Meaning | Fix |
|---|---|---|
401 Invalid gateway credential | The key is missing, unknown, expired, or disabled. | Check that LANGFUSE_GATEWAY_KEY is exported in the shell that runs the agent, and that the key is still active. |
401 on an OpenAI route with only x-api-key set | The OpenAI routes read the key only from Authorization: Bearer. | Send Authorization: Bearer <gateway key>. x-api-key works only on the Anthropic route. |
401 Conflicting gateway credentials in the Authorization and x-api-key headers | Both headers were sent with different values. Typical case: Claude Code with a leftover ANTHROPIC_API_KEY next to ANTHROPIC_AUTH_TOKEN. | Run unset ANTHROPIC_API_KEY, or give both the same value. For Pi, don't add a manual Authorization header next to apiKey. |
| 401 with a provider-looking key | The agent sends a stored provider credential instead of the gateway key (for example opencode auth or OPENAI_API_KEY). | Remove the stored credential or environment variable. |
403 Gateway access forbidden | The key belongs to a user who can no longer call the gateway (for example, their role changed to Viewer), or the organization has no usable ingestion project. | Check the key owner's organization role, and check that an ingestion project is set in Organization settings → AI Gateway → Setup. Role changes can take up to 60 seconds to reach existing keys. |
403 model_not_allowed | The model is turned off on the provider credential that serves the request. | Pick an enabled model from /models, or ask an admin to enable it. |
404 No eligible provider connection | No enabled provider credential serves this API format, for example a Claude Code call without an ANTHROPIC credential, or the model ID's prefix doesn't name a credential. | Add or fix the credential in Organization settings → AI Gateway → Setup, or use a model ID from /models. See model IDs. |
| 404 with an empty body on every call | Wrong path. | Claude Code and Pi use …/anthropic. OpenCode uses …/anthropic/v1. Everything on OpenAI uses …/openai/v1. Chat Completions is served at …/openai/v1/chat/completions. See your coding agent guide. |
404 not_found_error / model_not_found | The provider doesn't know the model, or your provider account has no access to it. On the Anthropic route, the gateway's own 404 errors also use the type not_found_error. | Read the error message: No eligible provider connection comes from the gateway (see the row above). Otherwise, check the ID with /models (see list models). A provider 404 is still recorded as ERROR. |
400 Invalid gateway model | The model ID has no credential prefix and doesn't start with gpt-, codex-, claude-, or ft:. | Use the <credential>:<model> ID from /models. See model IDs. |
400 Unsupported parameter: 'reasoning.effort' (Codex) | A global model_reasoning_effort was sent to a non-reasoning model. | Remove it, or use a reasoning model. |
400 Tool 'tool_search' is not supported with <model> (Codex) | The small model rejects Codex's tools. | Use a larger model. |
413 Request body exceeds gateway limit | The request is larger than 16 MiB (large contexts or screenshots). | Compact the conversation or start a new session. |
415 Unsupported request Content-Encoding | The request body is compressed (a Content-Encoding header other than identity). The gateway only accepts uncompressed bodies. | Turn off request compression in the client. |
429 Langfuse AI Gateway rate limit exceeded | Your organization hit its per-minute request or request-size limit on Langfuse Cloud. | Wait for the Retry-After time. Most clients retry on their own. If you hit it regularly, upgrade your plan or contact support. |
502 Upstream request failed | The gateway couldn't reach the provider, or the provider connection failed mid-request. | Retry. The call is recorded as ERROR. Report it with the request ID if it persists. |
504 Upstream deadline exceeded, or a stream that stops | The call hit the 600-second overall limit, or the provider sent nothing for 120 seconds. | Known beta limits. Split very long generations. The call is recorded as ERROR. |
503 Gateway temporarily unavailable | The gateway is at capacity or briefly can't reach Langfuse. | Retry with backoff. Report it with the request ID if it persists. |
| Client crashes on the last chunk of a streamed Chat Completions response | The gateway requests streaming usage upstream, so the stream ends with a usage chunk whose choices array is empty. | Skip chunks without choices. See streaming usage. |
| No session on Pi Anthropic traces | Pi doesn't send its session ID to Anthropic by default. | Add "compat": { "sendSessionAffinityHeaders": true }. See Pi. |
Traces in default despite langfuse-environment | The value doesn't match the environment format, so it fell back to default. | Use lowercase letters, numbers, - and _, at most 40 characters, not starting with langfuse. |
Six ERROR generations over about 70 seconds (OpenCode) | OpenCode retries OpenAI 404 errors with backoff. Anthropic 404 errors are not retried. | Fix the model ID. The duplicates are client retries. |
Two ERROR generations per failed prompt (Claude Code) | Claude Code retries once without streaming. | Expected. |
| All your sessions merged into one | A static langfuse-session-id in the config. | Remove it, or set it from a per-run environment variable. |
| Every Claude Code call is still its own trace with turn grouping enabled | Claude Code only sends traceparent when tracing is active. | Set all of CLAUDE_CODE_ENABLE_TELEMETRY, CLAUDE_CODE_ENHANCED_TELEMETRY_BETA, CLAUDE_CODE_PROPAGATE_TRACEPARENT, and a real OTEL_TRACES_EXPORTER (not none). See turn grouping. |
Was this page helpful?
Last updated on
