# Troubleshooting (/docs/troubleshooting)

Fix the common errors first — 401 and 404 from a wrong base URL or key, 429 quotas and rate limits, GitHub Copilot BYOK pitfalls, sign-in problems in the apps.

Most failures come from four things: the base URL, the key, a limit, or a client setting. Check them in that order.

## 401 Unauthorized [#401-unauthorized]

The gateway did not accept the key.

- Keys start with `codai_`. Anything else (an OpenAI `sk-…` key, a placeholder like `ck-…`) is rejected.
- Send it as `Authorization: Bearer codai_…` (OpenAI and Responses wire format) or `x-api-key: codai_…` (Anthropic wire format).
- A revoked or expired key answers 401 too. Open [hub.codai.ro](https://hub.codai.ro) → **API keys**, check the key is active, or create a new one.
- Watch for invisible characters: a key pasted from a phone keyboard can gain a trailing space or an auto-inserted character.

```bash
curl -sS https://ai.codai.ro/v1/models -H "Authorization: Bearer $CODAI_API_KEY"
```

A JSON list of models means the key works; anything else tells you what to fix.

## 404 Not Found [#404-not-found]

The URL is wrong, not the key.

| Client type | Base URL |
| --- | --- |
| OpenAI SDKs, Responses, most IDE plugins | `https://ai.codai.ro/v1` |
| Anthropic SDKs and Anthropic-type clients | `https://ai.codai.ro` (no `/v1`, the SDK adds it) |
| codai SDKs | none needed, the default is correct |

- The host is `ai.codai.ro`. Other hosts (`api.codai.ro`, `codai.ro`) do not serve the inference API.
- A doubled path (`/v1/v1/chat/completions`) is a 404: the client already appends `/v1`.
- The model name is `codai`. See [models](./gateway/models.mdx) for the names a client may send.

## 429 Too Many Requests [#429-too-many-requests]

Read the `error.code` in the body and the `Retry-After` header.

| Code | Meaning | What to do |
| --- | --- | --- |
| `rate_limit_exceeded` | A request or token window is full, or a daily or monthly spend cap was reached | Wait the `Retry-After` seconds; raise the per-key budget in the hub if it is your own cap |
| `quota_exceeded` | The task allowance of your plan is used up | Wait for the reset shown in `Retry-After`, top up credits, or change plan |

The [SDKs](./sdks/index.mdx) retry 429 with backoff automatically. Limits per plan are on [limits and pricing](./gateway/limits-pricing.mdx).

## GitHub Copilot (BYOK) [#github-copilot-byok]

- **The CLI says "Authentication failed (HTTP 401)" with type `anthropic`.** The base URL ends in `/v1`; the real answer is a 404. Use the root URL `https://ai.codai.ro`.
- **The model is missing from the picker.** Restart VS Code and check that your organisation's Copilot policy allows your own keys.
- **Agent mode is greyed out.** Set `toolCalling` to `true` on the model entry.
- **Inline completions and embeddings still go to GitHub.** That is expected: Copilot sends only chat and agent traffic to a BYOK model.

The full setup is in [GitHub Copilot](./integrations/github-copilot.mdx).

## Sign-in in the apps [#sign-in-in-the-apps]

- **Desktop, VS Code and the codaid CLI** sign in with a device code: a browser page opens with the code already filled in. If it does not open, visit `auth.codai.ro/device` and type the code shown in the app.
- **The code expired.** Codes are short-lived; start the sign-in again.
- **Signed in on the web but the app still asks.** Each app receives its own key and appears as a device in the hub under **Security → Devices**. Revoking that device signs the app out.
- **Linux desktop cannot store the key.** The app keeps its key in the system secret store; install and unlock one (GNOME Keyring or KWallet) and sign in again.

## Still stuck [#still-stuck]

See [support](./support.mdx) for how to reach us and what to include in the message.