--- title: How do I troubleshoot AI Gateway errors? description: Meanings and fixes for common AI Gateway HTTP errors, client failures, duplicate generations, missing sessions, and trace-grouping issues. tags: [ai-gateway] --- # 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 `. `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](/docs/administration/rbac), 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](/docs/gateway/features/models#manage-models). | | **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](/docs/gateway/features/models#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](/integrations#developer-tools). | | **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](/docs/gateway/get-started/first-request#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 `:` ID from `/models`. See [model IDs](/docs/gateway/features/models#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 ` (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](/faq/all/ai-gateway-known-limitations#rate-limits-on-langfuse-cloud) 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](/docs/gateway/features/rest-api#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](/integrations/developer-tools/pi-agent-gateway#setup). | | 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](/integrations/developer-tools/claude-code-gateway#turn-grouping). | --- ## Agent Instructions This page is part of the [Langfuse](https://langfuse.com) documentation, published as plain Markdown for AI agents. Every page is available as Markdown by appending `.md` to its URL, or by sending an `Accept: text/markdown` header. This page: `https://langfuse.com/faq/all/ai-gateway-error-codes.md`. ### Querying these docs If the answer is not on this page, query the documentation instead of guessing: - **Semantic search** across all Langfuse docs, returning an answer with the relevant pages and excerpts. Ask a specific, self-contained question: ```bash curl -sG "https://langfuse.com/api/search-docs" --data-urlencode "query=How do I trace a LangGraph agent?" ``` - **Index of every page**: , with per-section indexes [llms-docs.txt](https://langfuse.com/llms-docs.txt), [llms-integrations.txt](https://langfuse.com/llms-integrations.txt), and [llms-self-hosting.txt](https://langfuse.com/llms-self-hosting.txt). ### Before writing Langfuse code - **Install the [Langfuse Agent Skill](https://langfuse.com/docs/api-and-data-platform/features/agent-skill).** It encodes Langfuse's own best practices for instrumentation, prompt management, and evaluation, and materially improves results. - **Read [What does a good trace look like?](https://langfuse.com/docs/observability/best-practices.md)** before instrumenting an application. - **Verify endpoints, parameters, and response fields** against the [API reference](https://api.reference.langfuse.com) instead of inferring them from code examples. - **Use the [Langfuse CLI](https://langfuse.com/docs/api-and-data-platform/features/cli)** (`npx @langfuse/cli api `) to read or write traces, prompts, datasets, and scores from the terminal. Found an error in these docs? Please open an issue at .