---
title: "Troubleshooting"
version: "v0.28.0"
canonical: "https://docs.obot.ai/llm-gateway/troubleshooting"
unreleased: false
---

# Troubleshooting

Start with the request's Obot provider endpoint, requested model, user, and time. An administrator or auditor can use **Operations > Audit Logs > LLM** to correlate the request with its recorded outcome. Remove API keys and sensitive prompts before sharing diagnostics.

<a id="obot-doc-authentication-fails"></a>

## Authentication fails

Confirm that the client sends an Obot API key with **LLM proxy access**, using the authentication format documented for that client. An upstream provider key does not authenticate the client to Obot. An expired or deleted authorization scope no longer grants access.

Check the key against `/api/me` as described in [Testing an API key](https://docs.obot.ai/v0.28.0/functionality/agent-auth-scopes.md#obot-doc-testing-an-api-key). A successful result verifies the key's identity; it does not prove the key has LLM proxy access or that its owner has model grants.

<a id="obot-doc-no-models-appear-or-a-model-is-denied"></a>

## No models appear or a model is denied

1. Open **LLM Gateway** as the affected user and check which models are available.
2. Ask an administrator to check the matching policies under **LLM Gateway > Profiles**. Administrators also need model grants.
3. Check that the provider is configured under **LLM Gateway > Providers** and that the intended model is listed under **Models** on the provider's page. If it's missing, select **Refresh models**.
4. Use the model name shown on **LLM Gateway**, in `provider/model` form, such as `anthropic/claude-sonnet-4-5`.

A configured provider does not grant every user access. See [Control model access](https://docs.obot.ai/v0.28.0/functionality/model-access-policies.md).

<a id="obot-doc-an-alias-fails-or-uses-an-unexpected-model"></a>

## An alias fails or uses an unexpected model

`llm` and `llm-mini` refer to global defaults. An administrator can inspect their targets with **Set Default Models** under **LLM Gateway > Providers**.

The alias must point to an active model, and the caller must have access to that model. See [Default models](https://docs.obot.ai/v0.28.0/llm-gateway/how-it-works.md#obot-doc-default-models).

<a id="obot-doc-the-endpoint-or-request-format-is-rejected"></a>

## The endpoint or request format is rejected

Check the client's base URL against the example on **LLM Gateway**. The gateway serves the OpenAI Chat Completions, OpenAI Responses and Anthropic Messages formats at one base URL for every model. Starting in v0.28.1, supported operations on these routes are restored. Deprecated provider routes retain [supported inference and model-listing paths](https://docs.obot.ai/v0.28.0/llm-gateway/compatibility.md#obot-doc-deprecated-provider-endpoints). For a legacy URL, confirm that its corresponding gateway provider is configured and that the model belongs to that provider. Both AWS legacy routes select `bedrock`; use the unified endpoint with a `bedrock_mantle/` model name for Bedrock Mantle. Check the route's imported key when it is enabled and supports the requested model; otherwise check the provider's normal key pool. Unsupported legacy operations remain unavailable.

For client-specific settings and known limits, see [Using with Claude Code](https://docs.obot.ai/v0.28.0/llm-gateway/connect-clients.md#obot-doc-using-with-claude-code), [Using with Codex](https://docs.obot.ai/v0.28.0/llm-gateway/connect-clients.md#obot-doc-using-with-codex) and [API compatibility](https://docs.obot.ai/v0.28.0/llm-gateway/compatibility.md#obot-doc-limitations).

<a id="obot-doc-a-request-is-blocked-or-limited"></a>

## A request is blocked or limited

A `429` response names the [budget](https://docs.obot.ai/v0.28.0/llm-gateway/how-it-works.md#obot-doc-administering-the-gateway) that would be exceeded and when more becomes available. A `413` response means the request body is larger than the gateway's request size limit, set under **LLM Gateway** → **Settings** (100 MB by default); a change to the limit applies at once on every replica. A blocked request names the [applied guardrail](https://docs.obot.ai/v0.28.0/functionality/guardrails.md#obot-doc-applied-guardrails) that blocked it, unless the applied guardrail has its own block message; an administrator can find it, and its outcome, on the request's entry in the LLM audit log under **Operations > Audit Logs**.

<a id="obot-doc-the-upstream-provider-rejects-the-request"></a>

## The upstream provider rejects the request

An administrator should inspect the provider and its keys under **LLM Gateway > Providers**, the upstream credentials, requested model or deployment, and any upstream quota or rate-limit error. Check network access from Obot to the provider. Repeatedly changing the user's Obot key will not repair an invalid upstream credential.

<a id="obot-doc-verify-the-repair"></a>

## Verify the repair

Repeat a small request using the same client and the affected user's access. Check the returned model and the new audit outcome. A successful request under an administrator's account does not establish another user's access. For an unreachable Obot service, continue to [deployment troubleshooting](https://docs.obot.ai/v0.28.0/operations/troubleshooting.md).
