Errors, cancellation, and compatibility

Handle typed SDK errors#

OxApiError exposes the HTTP status, bounded server error code/message, and request ID. OxTimeoutError exposes the configured timeout, and OxConnectionError represents transport or invalid-response failures.

import { OxApiError, OxTimeoutError } from "@ox/sdk";

try {
  await ox.models.list({ signal: request.signal, timeoutMs: 30_000 });
} catch (error) {
  if (error instanceof OxApiError) {
    reportRequestFailure(error.status, error.code, error.requestId);
  } else if (error instanceof OxTimeoutError) {
    reportTimeout(error.timeoutMs);
  }
}

Respond by status and close code#

HTTP 401 means the permanent server key is missing/invalid. 413 means the mint body is too large. 429 means the project mint quota was exceeded. 503 means the model, durable state, or admitted warm capacity is unavailable. WebSocket 1000 is a clean close; 1008 is policy/auth; 1009 is too large; 1011 is a runtime/relay failure. Retry only before a session is admitted, with capped exponential jitter, and mint a new secret for each attempt.

Maintain compatibility#

Integrations created before the Ox rename can continue importing @pandan/realtime; it re-exports @ox/sdk, @ox/sdk/browser, and @ox/sdk/livekit. New integrations should use the Ox package names and the current public preview origin, https://www.amerint.co.