Error Codes

Most Olyx responses that indicate a failure use an error string. Validation-heavy control-plane endpoints may return an errors array when multiple fields failed.

{ "error": "Description of what went wrong" }

{ "errors": ["Name can't be blank"] }

Errors raised by gateway protection mechanisms include a machine-readable code field alongside the human-readable message:

{ "error": "Kill switch engaged: hourly limit of $5.00 exceeded.", "code": "CIRCUIT_OPEN" }

Two response patterns are not errors even though they might look like one at first glance:

• Blocked requests return 200 with a reason field and no output. The request succeeded — a safety or routing rule decided not to forward it.
• Tool calls pending return 200 with status: "tool_calls_pending". The model is waiting on tool results — this is part of the normal agentic flow.

Both are described at the bottom of this page.

HTTP Status Codes

Auth Errors (401)

Budget Errors (402)

Rate & Spend Errors (429)

Validation Errors (422)

Blocked Requests (200 with reason)

A blocked response is not an HTTP error — it returns 200 with a reason field and no output. The request reached Olyx successfully; the safety or routing layer decided not to forward it to a model.

{ "reason": "No private model configured for sensitive routing", "step_id": 44 }

Common reasons:

Blocked steps are recorded in the trace with type: "blocked" and the reason string, visible in the execution graph on the dashboard.

Tool Calls Pending (200 with status)

When a model requests tool calls, the response is also 200 — not an error — with status: "tool_calls_pending":

{
  "tool_calls": [{ "id": "call_1", "name": "get_weather", "arguments": { "city": "London" } }],
  "step_id": 43,
  "status": "tool_calls_pending"
}

Execute each tool locally or via your MCP server, then call POST /api/v1/executions again with tool_results and parent_step_id to continue. See Executions for the full flow.

404 Scoping

404 is returned when a resource either doesn’t exist or belongs to a different account. This is intentional — your application cannot determine whether a resource exists across account boundaries.

Retry Guidance

Ruby SDK Errors

When using the Ruby SDK, HTTP errors are translated into typed Ruby exceptions.

CircuitBreakerError is the SDK’s primary fail-closed behavior: when the governed path is unavailable and the caller has not explicitly opted into fail_open, no prompt reaches a provider without Olyx’s PII scrubbing and audit trail.

begin
  result = client.execute(trace_id: trace.id, input: "...")
rescue Olyx::CircuitBreakerError => e
  # Gateway unreachable, fail-closed. Nothing was sent to the provider.
  render json: { error: "AI service temporarily unavailable." }, status: :service_unavailable
rescue Olyx::RateLimitError => e
  case e.code
  when "CIRCUIT_OPEN"   then :reset_key_in_dashboard
  when "LOOP_DETECTED"  then :investigate_loop_then_reset_key
  else :wait_for_window_reset
  end
rescue Olyx::AuthError
  # Rotate key in Settings → API Keys
end

See the Ruby SDK error reference and Safety Valve for the full fail-open/closed behaviour.

Python SDK Errors

When using the Python SDK, HTTP errors are translated into typed Python exceptions.

CircuitBreakerError is the SDK’s primary fail-closed behavior: when the governed path is unavailable and the caller has not explicitly opted into fail_open, no prompt reaches a provider without Olyx’s PII scrubbing and audit trail.

try:
    result = client.execute(trace_id=trace.id, input="...")
except olyx.CircuitBreakerError:
    # Gateway unreachable, fail-closed. Nothing was sent to the provider.
    return {"error": "AI service temporarily unavailable."}, 503
except olyx.RateLimitError as e:
    if e.code == "CIRCUIT_OPEN":
        pass  # reset key in dashboard
    elif e.code == "LOOP_DETECTED":
        pass  # investigate loop, then reset key
    else:
        pass  # wait for window to reset
except olyx.AuthError:
    pass  # rotate key in Settings → API Keys

See the Python SDK error reference and Safety Valve for the full fail-open/closed behaviour.

TypeScript SDK Errors

When using the TypeScript SDK, HTTP errors are translated into typed JavaScript errors.

import { AuthError, CircuitBreakerError, RateLimitError } from "@olyx-labs/olyx";

try {
  const result = await client.execute({ traceId: trace.data.id, input: "..." });
} catch (err) {
  if (err instanceof CircuitBreakerError) {
    res.status(503).json({ error: "AI service temporarily unavailable." });
  } else if (err instanceof RateLimitError) {
    if (err.code === "CIRCUIT_OPEN") {
      // Review spend, then reset the key.
    }
    if (err.code === "LOOP_DETECTED") {
      // Investigate the loop, then reset the key.
    }
  } else if (err instanceof AuthError) {
    // Rotate key in Settings -> API Keys.
  } else {
    throw err;
  }
}

See the TypeScript SDK error reference and Safety Valve for SDK-specific fail-open/closed behavior.