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) |
| Kodwen 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
kodwen. 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.
402, 403 and 503 on a working key
| Status and code | Meaning | What to do |
|---|---|---|
402 cost_ceiling_reached | Your plan's monthly model-usage ceiling is reached and the wallet is empty. The body carries ceiling_eur, spent_eur, resets_at and topup_url | Top up the wallet (requests above the ceiling are paid from it), upgrade, or wait for resets_at |
403 account_disabled | The account is suspended or deleted; every key and sign-in token is refused | Contact Kodwen support |
503 budget_check_unavailable | The usage budget could not be checked for a moment | Retry after a minute |
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
Every app gets its own codai_ key and shows up as a device in hub.codai.ro under Security → Devices. Signing in on the web does not sign in the apps, and revoking a device signs only that app out.
Desktop
Continue in browser opens auth.codai.ro in your default browser. When you finish there, the browser sends you back to a small listener the app started on 127.0.0.1, and the app saves the key.
- Finish in a browser on the same computer. The redirect goes to
127.0.0.1, so a browser on another device cannot complete it. If the wrong browser opened, use the copy button next to the address in the app and paste it into a browser on this computer. - "Sign-in timed out." The app waits 10 minutes. Press Continue in browser again.
- The browser says the page cannot be reached after you sign in. A firewall or proxy blocks
127.0.0.1. Allow local connections for the browser, or use I have an API key with a key from the hub. - Where the key is kept. In the system credential store: Windows Credential Manager, the macOS Keychain or the Secret Service on Linux (GNOME Keyring or KWallet), under
ro.codai.desktop. When no store is available, the app keeps secrets in a file only your user can read, and Settings says so. On Linux, install and unlock GNOME Keyring or KWallet, then sign in again to move the key into it. See Linux dependencies.
Android
Sign-in happens inside the app: email and password, Sign in with Google, a passkey, or Continue with GitHub. The Google Play build and the APK build sign in the same way.
- GitHub opens a browser tab and does not come back. The GitHub step runs in a Chrome Custom Tab and returns through a
ro.codai.phone://link. If Android asks which app should open it, pick Kodwen. If the app says the sign-in expired, start again: the link is valid for about 10 minutes. - "No browser" error. The GitHub step needs a browser that can show a Custom Tab. Install or enable Chrome (or another browser), or sign in with email, Google or a passkey.
- Google sign-in is unavailable. It needs Google Play services. Use email, GitHub or a passkey instead.
- The app asks for a code after your password. Your account has two-step verification. Enter the 6-digit code from your authenticator app, a recovery code, or use your passkey.
- GitHub Copilot as your own provider (Settings → Providers → GitHub Copilot) uses a separate GitHub code: enter it at
github.com/login/device. It does not sign you in to Kodwen.
VS Code
Run Kodwen: Sign in and pick one of three ways:
- Continue with GitHub uses the GitHub account VS Code is already signed in to. If no Kodwen account uses that GitHub account yet, the extension switches to the browser code, because a new account must accept the Terms and confirm you are 18 or older in the browser.
- Sign in in the browser opens
auth.codai.ro/devicewith a one-time code filled in and copied to the clipboard. If the page does not open, visit that address and type the code. Codes are short-lived; if it expired, run the command again. - Use an API key… accepts a
codai_key from the hub.
Signing in to the extension does not add Kodwen as a model in Copilot Chat. That is a separate setting in Copilot; follow GitHub Copilot (BYOK).
Cursor, Windsurf and VSCodium install extensions from Open VSX, where Kodwen is not published yet. Install the .vsix by hand: see VS Code → Other editors.
codaid CLI
codaid login uses the same browser code as VS Code. On a server without a browser, open auth.codai.ro/device on any device and type the code shown in the terminal. For CI, set CODAI_API_KEY instead. Details on codaid.
Still stuck
See support for how to reach us and what to include in the message.