DocsHelp
Troubleshooting
Fixes for the problems people hit most: wrong base URLs, keys, instances that are still starting, tool calls, context limits and timeouts.
Start with these three checks; they solve most problems:
Terminal
# 1. Does the key work, and which models can it reach?
curl "https://osarai.xyz/v1/models" -H "Authorization: Bearer $OSARAI_API_KEY"
# 2. Does the model answer?
curl "https://osarai.xyz/v1/chat/completions" \
-H "Authorization: Bearer $OSARAI_API_KEY" \
-H "Content-Type: application/json" \
-d '{"model": "qwen3.8-27b", "messages": [{"role": "user", "content": "ping"}], "max_tokens": 8}'
# 3. Is the variable set in this shell?
echo "${OSARAI_API_KEY:0:8}"Connection and authentication
| Symptom | Cause | Fix |
|---|---|---|
401 Invalid or missing API key | The key is missing, mistyped or revoked | Check echo "${OSARAI_API_KEY:0:8}" prints qck_ and a few characters; create a new key if it was revoked |
401 only in one tool | The tool reads another variable (OPENAI_API_KEY, ANTHROPIC_AUTH_TOKEN) | See the tool's guide for the variable it uses |
404 Not Found on every request | The base URL is wrong | OpenAI clients: https://osarai.xyz/v1. Anthropic clients: https://osarai.xyz |
404 on /v1/v1/… | /v1 was added twice | Remove one; Anthropic clients add /v1 themselves |
Requests reach api.openai.com | The tool ignored your base URL | Set it in the tool's config file, not only in the environment |
Instance state
| Symptom | Cause | Fix |
|---|---|---|
503 … no instance is running | Nothing is deployed, or it stopped | Deploy from the dashboard; instances stop after the idle timeout or when the balance runs out |
503 … not ready yet | The instance is still starting | Wait for Ready; the message names the current step. First starts take 10 to 20 minutes |
502 | The instance did not answer | Retry; if it repeats, open the instance page and check its status |
404 model_not_found | Several instances run different models and model matches none | Use an id from /v1/models, or pin one with X-Instance-Id |
Agents and tool calls
| Symptom | Fix |
|---|---|
| The agent chats but never reads or edits files | The model needs tool calls: use qwen3.8-27b (or gpt-oss for Codex), and enable tool support in the tool's model settings |
| The agent stops halfway through a long task | It reached the context window: set the real window in the tool's config so it compacts in time (Coding agents) |
400 … prompt is too long / maximum context length | The conversation outgrew the window; start a new session or compact |
| Answers are cut off | max_tokens is too low, or the tool caps output; raise it up to the model's max output (Models) |
| Thinking takes too long | Lower the reasoning effort, or turn thinking off for quick edits |
Timeouts and slow first tokens
- A long prompt can take a while before the first token. Streaming responses send keepalives during that time, so prefer
"stream": true. - Set your client's timeout to a few minutes or more (the OpenAI Python SDK allows
timeout=900). A single request can run for up to 15 minutes. - The first request after a start loads the model's caches and is slower than the ones after it.
Rate limits
429 Rate limit exceeded means more requests per minute than the key allows (120 by default). Wait for Retry-After seconds, or create a key with a higher limit (up to 600). Tokens are never rate limited.
Still stuck?
Open Support in the dashboard and include the time of the request, the endpoint and the error body. Never paste your API key.