Troubleshooting
Fixes for every common Ostra error — authentication, permissions, balance and spend limits, rate limits, cold starts, broken streams, MCP connection problems, empty answers, defer answers and cache surprises — plus an FAQ.
Every error carries a type and a request_id. Search for the request id in the Console under Logs to see the full request, response and timing. The full catalogue is in Errors.
| You see | Cause | Fix |
|---|
401 "Missing API key. Send Authorization: Bearer ostk_live_…." | No Authorization header, or not Bearer. On /predict, /batch, /models and /mcp, x-api-key isn't accepted. | Send Authorization: Bearer $OSTRA_API_KEY. Check the variable is set in the environment that runs the request (CI secrets often aren't passed to every step). |
401 "Invalid API key." | The key is mistyped, truncated, or from another environment. | Copy the whole key (50 characters, starting ostk_live_). Create a new one if you lost it: keys are shown once. |
401 "This API key has been revoked." | Someone revoked it in API keys. | Create a new key and update your secrets. |
401 "This API key has expired." | The key passed its expiry. | Create a new key. The workspace's key policy may require an expiry; plan rotations. |
403 "Requests from this IP address are not allowed for this API key." | The key has an IP allowlist and the caller isn't on it. Hosted CI runners change IPs. | Add the address or CIDR range in API keys → Edit, or use a key without an allowlist for that system. |
403 "This API key is read-only and cannot run predictions." | A Read only key called a route that runs a model. | Use a Full access key. Read-only keys can only list models and warm Ostra Pro. |
403 / MCP isError: "The … tool is disabled for your organization." | The tool is turned off in MCP servers → Tools. | Ask an owner, admin or developer to turn it back on. REST is unaffected. |
| You see | Cause | Fix |
|---|
402 insufficient_balance | The balance doesn't cover the request. For Ostra Pro the check is against the request's maximum cost. | Top up in Billing → Buy Credits, or turn on auto top-up. For Ostra Pro, lowering max_tokens lowers the amount held. |
402 spend_limit_reached, scope: "org" | This month's workspace spend reached the monthly spend limit. | Raise or clear the limit in Billing → Edit limit, or wait for the next calendar month (UTC). |
402 spend_limit_reached, scope: "key" | This key's monthly spend cap is reached. | Raise the cap in API keys → Edit, or use another key. |
| Auto top-up stopped | Three failed charges in a row turn it off. | Update the card in Billing → Manage payment method, then switch auto top-up back on. |
See Billing and credits.
| You see | Cause | Fix |
|---|
429 rate_limit_exceeded | Your workspace used its requests for this minute. Every key, MCP client and Playground run shares the count. | Wait Retry-After seconds. Batch Ostra Decision work with /batch; raise your usage level by topping up; check for a key with a low RPM override. |
503 with state: "starting" | Ostra Pro is starting after 5 quiet minutes. | Retry after Retry-After (60 s), use "stream": true (it waits), or call POST /warm first. Nothing was charged. |
503 "at capacity" | Ostra Pro is busy. | Retry after Retry-After (5 s). |
503 "Too many requests are updating this workspace's balance at once." | Many requests finished at the same moment. | Retry after 1 s. Nothing was charged. |
502 upstream_error, 504 upstream_timeout | The model failed or didn't answer in time. | Retry with backoff. Nothing was charged. |
| You see | Cause | Fix |
|---|
The stream ends without data: [DONE] (OpenAI format) or message_stop (Anthropic format) | It failed after starting; the last event is data: {"error": …} (or event: error). | Treat it as failed and retry. You're charged only for the tokens produced. |
Lines starting with : ostra-pro is starting | Keep-alive comments while Ostra Pro starts. | Nothing: SSE parsers ignore comment lines. |
| A proxy or load balancer cuts long streams | An idle timeout in your network. | Ostra sends keep-alives every ~10 s while starting; raise the proxy's idle timeout above 30 s. |
| You see | Cause | Fix |
|---|
Empty content, finish_reason: "length" | Reasoning used up max_tokens before the answer. | Raise max_tokens or lower reasoning_effort. Over MCP the tool says "Raise max_tokens or lower reasoning_effort." |
| Answers are slow or expensive | Thinking is on at xhigh by default. | Use reasoning_effort: "low" or "medium", or turn thinking off with chat_template_kwargs.enable_thinking: false. |
cached_tokens stays at 0 on follow-up turns | Each turn landed on a different replica, or the prompt prefix changed. | Send x-ostra-session with one value per conversation, and keep the start of the prompt unchanged. See Sessions and caching. |
400 "Ostra Pro takes text, image_url and video_url parts." | An unsupported content part (for example audio). | Send text, images or one video. |
| You see | Cause | Fix |
|---|
defer with insufficient_evidence | The request said nothing about this test or locator: no history, diff or DOM check. | Add at least one of memory, diff or dom (triage), history or dom_locator_found (selector survival). |
defer with below_threshold | The evidence points two ways. | Look at probabilities for the runner-up; send it to a person or add evidence. |
defer with model_gate_failed | That task's model is held back by its release quality gate. | Treat as no answer until the next release. |
The same answer every time, cached: true | Identical input within 24 hours is served from cache. | Expected. Change the input (for example add new history) to get a fresh answer. |
400 "context needs error_class, or error_message to derive it from." | A triage request without either. | Send the raw error_message (or a known error_class). |
400 naming a field, for example context.memory.runs_50: Input should be less than or equal to 50 | A value is out of range or a field is unknown. | Fix the field named in param/the message. Unknown fields are rejected. |
test_impact returns selection: "none" | No candidate had co-change or failure-rate evidence. | Run the full suite, and add co_change_rate from git log. See Run only impacted tests. |
| You see | Cause | Fix |
|---|
| Claude Code: "Dynamic Client Registration" or "needs authentication" | The Authorization header didn't reach the client, so it tried OAuth. Usually a line break in the claude mcp add command. | claude mcp remove ostra, then run the add command again on one line. |
| Empty replies or dropped connections | Antivirus HTTPS scanning (a "web shield") interfering with streamed responses. | Exclude ostra.testrelic.ai from HTTPS scanning and reconnect. |
Tools are listed but every call fails with permission_error | A read-only key. | Use a Full access key. |
| A tool is missing from the list | It's turned off in MCP servers → Tools. | Turn it back on. |
400 with JSON-RPC error -32600 about the protocol version | The client sent an unsupported MCP-Protocol-Version. | Use a client that supports 2025-06-18 or 2025-03-26. |
| The client doesn't appear under Clients | It hasn't connected yet, or it's using a different key's workspace. | Make one call (for example ostra_list_models); it appears within a minute. |
| You see | Cause | Fix |
|---|
| Every page sends you to billing setup | The workspace has no billing details yet. | An owner, admin or billing member completes Billing details. Other roles see "Waiting for billing setup". |
| Get started checklist doesn't tick | Steps tick automatically from real data and can take a moment to refresh. | Complete the step (for example make one request), then reload. |
| "Your role can't change this. Ask an admin." | Your role doesn't allow the action. | See the roles table in Workspaces and members. |