> ## Documentation Index
> Fetch the complete documentation index at: https://copilot-api.nick3.top/llms.txt
> Use this file to discover all available pages before exploring further.

# Troubleshoot common Copilot API issues

> Diagnose and fix authentication failures, Admin UI access errors, token counting mismatches, and other common Copilot API problems.

If something is not working as expected, start with the built-in diagnostic commands and then work through the relevant section below.

```bash theme={null}
# Show version, runtime info, file paths, and authentication status
npx @nick3/copilot-api@latest debug

# Show debug output as JSON
npx @nick3/copilot-api@latest debug --json

# Show current Copilot usage and quota (no server required)
npx @nick3/copilot-api@latest check-usage
```

<AccordionGroup>
  <Accordion title="Authentication errors">
    Run `debug` to check your current authentication status:

    ```bash theme={null}
    npx @nick3/copilot-api@latest debug
    ```

    If the output shows missing or expired tokens, re-run the auth flow:

    ```bash theme={null}
    npx @nick3/copilot-api@latest auth
    ```

    This opens the GitHub OAuth device flow and refreshes your stored credentials. After authenticating, start the proxy again and retry.
  </Accordion>

  <Accordion title="403 from Admin UI or Admin API">
    A `403 Forbidden` response means the request came from a non-loopback address and `ADMIN_TOKEN` is not set on the server.

    The Admin UI is restricted to `localhost`, `127.0.0.1`, and `::1` by default. For remote access, set the `ADMIN_TOKEN` environment variable when starting the proxy:

    ```bash theme={null}
    ADMIN_TOKEN=your_admin_token_here npx @nick3/copilot-api@latest start
    ```

    Then include the token in every Admin API request:

    ```bash theme={null}
    curl -H "x-admin-token: your_admin_token_here" \
      "http://your-host:4141/api/admin/meta"
    ```

    See [Monitor usage with the Admin UI](/guides/admin-ui) for full access control details.
  </Accordion>

  <Accordion title="401 from Admin UI or Admin API">
    A `401 Unauthorized` response means `ADMIN_TOKEN` is configured on the server but your request did not include the token.

    Pass the token using the `x-admin-token` header or `Authorization: Bearer`:

    ```bash theme={null}
    curl -H "x-admin-token: your_admin_token_here" \
      "http://localhost:4141/api/admin/accounts"
    ```

    The UI stores the token in `sessionStorage` and sends it automatically once you enter it in the **Admin token** dialog in the top-right corner.
  </Accordion>

  <Accordion title="&#x22;Prompt token count exceeds limit&#x22; errors with Claude Code">
    Claude Code compacts conversation history based on token counts reported by the proxy. By default, the proxy estimates Claude token counts using the GPT `o200k_base` tokenizer with a multiplier. This consistently underestimates actual Claude usage, causing Claude Code to compact too late and hit the context limit.

    Fix this by configuring an Anthropic API key. The proxy then forwards token counting requests for Claude models to Anthropic's real `/v1/messages/count_tokens` endpoint, which returns exact counts. The token counting endpoint is free — you only need a minimum \$5 credit balance on your Anthropic account to activate API access.

    Add the key to `config.json`:

    ```json config.json theme={null}
    {
      "anthropicApiKey": "sk-ant-..."
    }
    ```

    Or set it as an environment variable:

    ```bash theme={null}
    ANTHROPIC_API_KEY=sk-ant-... npx @nick3/copilot-api@latest start
    ```

    See the [configuration reference](/configuration/config-file) for setup steps.
  </Accordion>

  <Accordion title="Rate limit errors">
    If you are receiving rate limit errors from the proxy or from GitHub Copilot, use the `--rate-limit` and `--wait` flags to pace your requests:

    ```bash theme={null}
    # Enforce a 30-second gap between requests
    npx @nick3/copilot-api@latest start --rate-limit 30

    # Wait instead of returning an error when the cooldown is active
    npx @nick3/copilot-api@latest start --rate-limit 30 --wait
    ```

    See [Control request rate limits in Copilot API](/guides/rate-limiting) for more options.
  </Accordion>

  <Accordion title="GitHub security warning or account suspension">
    If you receive a security warning from GitHub or your Copilot access is temporarily suspended, you are likely sending too many automated requests too quickly.

    Steps to take:

    1. Stop the proxy and wait for any suspension to lift.
    2. Reduce request frequency using `--rate-limit` (for example, `--rate-limit 60`).
    3. Review [GitHub's Acceptable Use Policies](https://docs.github.com/site-policy/acceptable-use-policies/github-acceptable-use-policies#4-spam-and-inauthentic-activity-on-github) and [GitHub Copilot Terms](https://docs.github.com/site-policy/github-terms/github-terms-for-additional-products-and-features#github-copilot).
    4. Avoid running bulk or parallel automated workloads through the proxy.
  </Accordion>

  <Accordion title="Token counting is inaccurate for Claude models">
    The default GPT tokenizer used for `/v1/messages/count_tokens` underestimates actual Claude token usage. This causes tools like Claude Code to compact too late and can produce context-limit errors.

    For exact counts, provide an Anthropic API key. Set it in `config.json`:

    ```json config.json theme={null}
    {
      "anthropicApiKey": "sk-ant-..."
    }
    ```

    Or via environment variable:

    ```bash theme={null}
    ANTHROPIC_API_KEY=sk-ant-...
    ```

    When the key is present, the proxy forwards Claude token counting requests to Anthropic's `/v1/messages/count_tokens` endpoint (which is free to call). Non-Claude models and failures fall back to GPT tokenizer estimation automatically.
  </Accordion>

  <Accordion title="Requests are using premium quota unexpectedly">
    If requests you expect to be free are consuming premium quota, check two settings in `config.json`:

    1. Confirm `compactUseSmallModel` is `true` (the default). When enabled, compact and background requests from Claude Code or OpenCode are routed to `smallModel` instead of your premium model.
    2. Confirm `smallModel` points to a free-tier model such as `gpt-5-mini`.

    ```json config.json theme={null}
    {
      "smallModel": "gpt-5-mini",
      "compactUseSmallModel": true
    }
    ```

    You can verify which model handled each request using the [Admin UI](/guides/admin-ui) Requests view and inspecting the `upstream_model` field.
  </Accordion>

  <Accordion title="Enable detailed diagnostic logs">
    For payload-level or stream-level diagnostics, set `logLevel` to `debug` in `config.json`:

    ```json config.json theme={null}
    {
      "logLevel": "debug"
    }
    ```

    The proxy writes detailed logs to `logs/*.log` under the app data directory (`~/.local/share/copilot-api/` on Linux/macOS). After adding this setting, restart the proxy for it to take effect.

    <Note>
      `--verbose` on the command line does not enable debug-level file logging. You must set `logLevel` in `config.json` explicitly.
    </Note>
  </Accordion>
</AccordionGroup>