Errors
The Ostra error envelope, every error type and HTTP status, the messages you can see, which errors to retry and how, and the Anthropic and MCP error shapes.
The envelope
Every error is JSON with the same shape, whatever the route:
{
"error": {
"type": "insufficient_balance",
"message": "Your balance ($0.00) does not cover this request ($0.0000005). Top up in the TestRelic Console.",
"balance_usd": "0.00",
"cost_usd": "0.0000005",
"request_id": "req_01JDXK8B9C0D1E2F3G4H5J6K7L"
}
}typeis stable: branch on it, not onmessage.messageis written for people and may change.request_idmatches thex-request-idheader. Quote it to support.- Some errors add fields, listed below.
Types
| Status | type | Retry? | Meaning |
|---|---|---|---|
| 400 | invalid_request | No | The body isn't JSON, a field is missing or invalid (param names it), or the model rejected the input. |
| 401 | authentication_error | No | Missing, malformed, unknown, revoked or expired key. |
| 402 | insufficient_balance | No | Credit balance too low. Adds balance_usd, cost_usd. |
| 402 | spend_limit_reached | No | The workspace's monthly spend limit (scope: "org") or the key's monthly cap (scope: "key") is reached. |
| 403 | permission_error | No | IP not in the key's allowlist, read-only key on a route that runs a model, or an MCP tool your workspace turned off. |
| 404 | not_found | No | No such route. The message names the API and MCP base URLs. |
| 405 | invalid_request | No | Wrong HTTP method for the route. |
| 409 | conflict | No | The request conflicts with the workspace's state. |
| 413 | payload_too_large | No | Body over the route's limit: 2 MB for Ostra Decision and MCP, 5.5 MB for Ostra Pro. |
| 429 | rate_limit_exceeded | Yes, after Retry-After | Requests-per-minute limit reached. Adds retry_after_ms. |
| 500 | internal_error | Yes, with backoff | Unexpected error on our side. |
| 502 | upstream_error | Yes, with backoff | The model failed to answer. Nothing was charged. |
| 503 | service_unavailable | Yes, after Retry-After | Ostra Pro is starting (state: "starting") or at capacity, or the workspace balance is busy. Nothing was charged. Adds retry_after_ms. |
| 504 | upstream_timeout | Yes, with backoff | The model didn't answer in time. Nothing was charged. |
Extra fields
| Field | On | Meaning |
|---|---|---|
param | 400 | The field that failed, e.g. task or messages[0].role. |
balance_usd, cost_usd | 402 | Your balance and what the request needed (for Ostra Pro, its maximum cost). |
scope | spend_limit_reached | org (workspace limit) or key (key cap). |
retry_after_ms | 429, 503 | How long to wait, in milliseconds. The Retry-After header has the same in seconds. |
state | 503 | starting while Ostra Pro starts after a quiet period. |
Messages you may see
Retrying
Retry only 429, 500, 502, 503 and 504. Wait Retry-After when it's present; otherwise back off exponentially (1 s, 2 s, 4 s, with jitter), up to 3 or 4 attempts. Failed requests are never charged, so retries are safe to pay for, but Ostra has no idempotency keys: a retried Ostra Pro request generates a new answer.
import os
import random
import time
import requests
RETRY = {429, 500, 502, 503, 504}
def ostra_post(path: str, body: dict, attempts: int = 4) -> dict:
url = f"https://ostra.testrelic.ai/api/v1{path}"
headers = {"Authorization": f"Bearer {os.environ['OSTRA_API_KEY']}"}
for attempt in range(attempts):
response = requests.post(url, headers=headers, json=body, timeout=120)
if response.status_code not in RETRY or attempt == attempts - 1:
break
wait = float(response.headers.get("retry-after") or 2**attempt + random.random())
time.sleep(min(wait, 60))
if not response.ok:
error = response.json().get("error", {})
raise RuntimeError(f"Ostra {response.status_code} {error.get('type')}: {error.get('message')} ({error.get('request_id')})")
return response.json()OpenAI and Anthropic SDKs already retry 429 and 5xx responses; leave their retry settings on.
Errors inside a stream
Once a stream has started (HTTP 200), a failure arrives as a final event instead of an HTTP status:
data: {"error":{"type":"upstream_error","message":"The Ostra Pro stream broke before it finished. You were charged only for the tokens produced.","request_id":"req_…"}}There's no [DONE] after it. See Streaming.
Anthropic shape on /messages
/api/v1/messages returns errors the way Anthropic SDKs expect, with the Ostra type kept in ostra_type:
{
"type": "error",
"error": { "type": "overloaded_error", "message": "…", "ostra_type": "service_unavailable", "retry_after_ms": 60000 },
"request_id": "req_…"
}| Ostra type | Anthropic type |
|---|---|
invalid_request, conflict | invalid_request_error |
authentication_error | authentication_error |
permission_error | permission_error |
insufficient_balance, spend_limit_reached | billing_error |
not_found | not_found_error |
payload_too_large | request_too_large |
rate_limit_exceeded | rate_limit_error |
internal_error, upstream_error | api_error |
service_unavailable | overloaded_error |
upstream_timeout | timeout_error |
MCP errors
On the MCP server, authentication and IP failures are HTTP 401/403 with the envelope above. Everything else about a tool call (validation, balance, rate limit, a disabled tool) comes back as a normal JSON-RPC result with isError: true and the same type in structuredContent.error. Protocol problems use JSON-RPC error codes: -32700 (bad JSON), -32600 (invalid request or unsupported protocol version), -32601 (unknown method), -32602 (unknown tool, missing tool name, or params that isn't an object; invalid tool arguments come back as isError: true with invalid_request), -32603 (internal error). See MCP.