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
The gateway did not accept the key.
- Keys start with
codai_. Anything else (an OpenAIsk-…key, a placeholder likeck-…) is rejected. - Send it as
Authorization: Bearer codai_…(OpenAI and Responses wire format) orx-api-key: codai_…(Anthropic wire format). - A revoked or expired key answers 401 too. Open 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.
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
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 for the names a client may send.
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 retry 429 with backoff automatically. Limits per plan are on limits and pricing.
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 URLhttps://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
toolCallingtotrueon 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.
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/deviceand 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
See support for how to reach us and what to include in the message.