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.

Authentication and permissions

You seeCauseFix
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.

Billing

You seeCauseFix
402 insufficient_balanceThe 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 stoppedThree 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.

Rate limits and availability

You seeCauseFix
429 rate_limit_exceededYour 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_timeoutThe model failed or didn't answer in time.Retry with backoff. Nothing was charged.

Streams

You seeCauseFix
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 startingKeep-alive comments while Ostra Pro starts.Nothing: SSE parsers ignore comment lines.
A proxy or load balancer cuts long streamsAn idle timeout in your network.Ostra sends keep-alives every ~10 s while starting; raise the proxy's idle timeout above 30 s.

Ostra Pro answers

You seeCauseFix
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 expensiveThinking 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 turnsEach 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.

Ostra Decision answers

You seeCauseFix
defer with insufficient_evidenceThe 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_thresholdThe evidence points two ways.Look at probabilities for the runner-up; send it to a person or add evidence.
defer with model_gate_failedThat 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: trueIdentical 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 50A 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.

MCP

You seeCauseFix
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 connectionsAntivirus 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_errorA read-only key.Use a Full access key.
A tool is missing from the listIt's turned off in MCP servers → Tools.Turn it back on.
400 with JSON-RPC error -32600 about the protocol versionThe 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 ClientsIt 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.

Console

You seeCauseFix
Every page sends you to billing setupThe 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 tickSteps 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.

FAQ

Was this page helpful?

On this page