> ## Documentation Index
> Fetch the complete documentation index at: https://docs.layerx1.com/llms.txt
> Use this file to discover all available pages before exploring further.

# When something isn't working.

> The failures people actually hit, in the order they hit them — what each one means and the one thing to change. Then how to reach us, and what to include so the first reply is the useful one.

## Start here

Three commands answer most of it before you read any further:

```sh theme={null}
npx layerx1 status              # what your tools are actually configured with
npx layerx1 test                # does the key reach the gateway at all
curl -s https://api.layerx1.com/v1/models | head   # is the gateway answering
```

## Authentication

<AccordionGroup>
  <Accordion title="401 — every request rejected">
    The key is missing, malformed, or in the wrong header for the dialect you're calling.
    Anthropic-style endpoints take `x-api-key`; OpenAI-style endpoints take
    `Authorization: Bearer`. `/v1/messages` accepts either. Keys always start with `lx1_`.
    See [Authentication](/authentication).
  </Accordion>

  <Accordion title="Claude Code ignores the gateway and talks to Anthropic">
    You are still logged in to Claude Code's own account, which takes precedence over the
    environment variables. Run `/logout` first, then re-run `npx layerx1`. Check
    `ANTHROPIC_BASE_URL` is the bare origin — `https://api.layerx1.com`, with **no** `/v1`;
    the Anthropic SDK appends the path itself.
  </Accordion>

  <Accordion title="Codex can't find a key / missing LAYERX1_API_KEY">
    Codex Desktop does not inherit User environment variables. Re-run
    `npx layerx1 setup --tool codex --key lx1_your_key` (0.2.4+) so the key is stored as
    `experimental_bearer_token` in `~/.codex/config.toml`. See [Codex CLI](/guides/codex).
  </Accordion>
</AccordionGroup>

## Models

<AccordionGroup>
  <Accordion title="404 — no such model">
    The id did not resolve. Check it against `GET /v1/models`. Unknown ids fail closed
    rather than silently becoming something else, and the compatibility handles for foreign
    SDK names are a finite list — an invented id is a `404` by design. See
    [Model routing](/guides/model-routing).
  </Accordion>

  <Accordion title="The model in the catalog page isn't in GET /v1/models">
    It is a **preview** id. The [Models](/models) page marks these in its Availability
    column: the name is accepted and answered from the serving pool, but no dedicated
    placement is routed for it yet, so it is not in the endpoint's list. Pin a **Live** id
    for anything whose exact behavior you depend on.
  </Accordion>

  <Accordion title="400 on a request with an image">
    That model does not accept image input. It is a short list — check
    `capabilities.vision` on the [catalog entry](/api/models-endpoint). See
    [Vision](/guides/vision).
  </Accordion>

  <Accordion title="422 — the model can't guarantee what you asked for">
    The request declared a hard requirement (a forced `tool_choice`, a strict
    `response_format`) that no placement of that model declares support for. Switch to a
    model whose `supported_parameters` includes it, or drop the requirement.
  </Accordion>
</AccordionGroup>

## Output

<AccordionGroup>
  <Accordion title="Empty response, or an answer that stops mid-sentence">
    `finish_reason: "length"` — you hit `max_tokens`. On a reasoning model, hidden
    reasoning is charged against the same ceiling and can consume all of it, leaving
    nothing for the answer. Raise the budget; 4,000+ is a safe floor on reasoning models.
    See [Reasoning](/guides/reasoning).
  </Accordion>

  <Accordion title="Unexpected thinking blocks break my client">
    Reasoning is hidden unless the request opts in. If you are seeing it, something in your
    stack is sending `thinking`, `reasoning_effort` or `reasoning` — often an SDK default.
    Remove it.
  </Accordion>

  <Accordion title="The stream just stops">
    A stream that cannot finish ends with a protocol-shaped error event, never a silent
    truncation — so check for one before assuming the model ran out of things to say. Treat
    a mid-stream error like a `5xx`: retry the whole request with backoff. See
    [Streaming](/guides/streaming).
  </Accordion>
</AccordionGroup>

## Limits and cost

<AccordionGroup>
  <Accordion title="429 with a short retry-after">
    A rate limit — requests/min or concurrency for your plan. Honor `retry-after` exactly
    and pace off the `x-ratelimit-*` headers instead of discovering the limit by hitting
    it. Parallel agent fleets usually hit **concurrency** first. See [Plans & limits](/plans).
  </Accordion>

  <Accordion title="429 allowance_exhausted">
    The month's included usage is spent. This is a hard cap: retrying will not clear it —
    `retry-after` is the seconds to reset. Upgrading lifts it immediately.
  </Accordion>

  <Accordion title="429 credits_exhausted with no retry-after">
    A prepaid balance at zero. There is no reset date to wait for, so there is no
    `retry-after` — only a top-up clears it. Branch on the two codes rather than retrying
    both.
  </Accordion>

  <Accordion title="Requests are slower than expected under load">
    When every model that could serve a request is at capacity, the request queues rather
    than being shed as a `429`. It shows up as latency, not an error — so give client
    timeouts headroom. See [Reliability](/reliability).
  </Accordion>

  <Accordion title="Usage is burning faster than expected">
    The pool is measured in list-price dollars, so heavier models drain it faster.
    `x1-allowance-remaining` on every response is the live figure. Two levers: move the hot
    path to a cheaper tier, and make the prompt prefix stable so repeated context bills at
    a cached rate where the model publishes one ([Prompt caching](/guides/prompt-caching)).
  </Accordion>
</AccordionGroup>

## Getting help

<Card title="support@layerx1.com" href="mailto:support@layerx1.com" horizontal>
  The fastest route for anything not answered above.
</Card>

Include these and the first reply can usually be the answer rather than a question:

* **What you sent** — endpoint, model id, and the request body with secrets removed.
* **What came back** — the status code and the full `error.message`.
* **When** — a rough timestamp with timezone, so the trace can be found.
* **The `x1-model` response header**, if you have it — it names what actually served the
  request.

Never send your API key. If you think one has leaked, revoke it in the dashboard first and
tell us second.