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"
  }
}
  • type is stable: branch on it, not on message.
  • message is written for people and may change.
  • request_id matches the x-request-id header. Quote it to support.
  • Some errors add fields, listed below.

Types

StatustypeRetry?Meaning
400invalid_requestNoThe body isn't JSON, a field is missing or invalid (param names it), or the model rejected the input.
401authentication_errorNoMissing, malformed, unknown, revoked or expired key.
402insufficient_balanceNoCredit balance too low. Adds balance_usd, cost_usd.
402spend_limit_reachedNoThe workspace's monthly spend limit (scope: "org") or the key's monthly cap (scope: "key") is reached.
403permission_errorNoIP not in the key's allowlist, read-only key on a route that runs a model, or an MCP tool your workspace turned off.
404not_foundNoNo such route. The message names the API and MCP base URLs.
405invalid_requestNoWrong HTTP method for the route.
409conflictNoThe request conflicts with the workspace's state.
413payload_too_largeNoBody over the route's limit: 2 MB for Ostra Decision and MCP, 5.5 MB for Ostra Pro.
429rate_limit_exceededYes, after Retry-AfterRequests-per-minute limit reached. Adds retry_after_ms.
500internal_errorYes, with backoffUnexpected error on our side.
502upstream_errorYes, with backoffThe model failed to answer. Nothing was charged.
503service_unavailableYes, after Retry-AfterOstra Pro is starting (state: "starting") or at capacity, or the workspace balance is busy. Nothing was charged. Adds retry_after_ms.
504upstream_timeoutYes, with backoffThe model didn't answer in time. Nothing was charged.

Extra fields

FieldOnMeaning
param400The field that failed, e.g. task or messages[0].role.
balance_usd, cost_usd402Your balance and what the request needed (for Ostra Pro, its maximum cost).
scopespend_limit_reachedorg (workspace limit) or key (key cap).
retry_after_ms429, 503How long to wait, in milliseconds. The Retry-After header has the same in seconds.
state503starting 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 typeAnthropic type
invalid_request, conflictinvalid_request_error
authentication_errorauthentication_error
permission_errorpermission_error
insufficient_balance, spend_limit_reachedbilling_error
not_foundnot_found_error
payload_too_largerequest_too_large
rate_limit_exceededrate_limit_error
internal_error, upstream_errorapi_error
service_unavailableoverloaded_error
upstream_timeouttimeout_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.

Was this page helpful?

On this page