Realtime, errors, and quotas

Realtime subscriptions reduce display latency. Indexed API reads and receipt status endpoints remain the durable way to establish state after startup, reconnect, or uncertainty.

const subscription = actionClient.realtime.subscribe({
  channels: [`account:${account}`, "market:1"],
  onEvent: (event) => console.info(event.eventId, event.data),
  onSnapshot: (snapshot) => console.info("snapshot", snapshot),
  onError: (error) => console.error(error),
});

// Later
subscription.close();

The SDK obtains a short-lived single-use ticket over authenticated HTTPS and puts only that ticket in the WebSocket URL. It never puts the API key in the URL. After an unexpected close, the client reconnects with exponential backoff from 500 milliseconds to 15 seconds. It obtains a new ticket, resumes each channel from its latest sequence, and removes duplicate event IDs in a rolling 2,048-event window. Snapshots establish a new channel cursor. Applications should make event handlers idempotent and refresh relevant API state if the server cannot satisfy a resume. Calling close() cancels a pending reconnect and closes the socket. At least one channel is required.

Error model

API and RPC failures use TayhoError:

try {
  await actionClient.markets.list();
} catch (error) {
  if (error instanceof TayhoError) {
    console.error(error.code, error.status, error.requestId);
  }
}

Code	Meaning	Caller response
`invalid_configuration`	Client options or deployment configuration are incompatible	Correct the environment, URL, signer, or reader; do not retry unchanged
`authentication_failed`	Key is missing, invalid, expired, revoked, or suspended	Replace or reactivate the key
`forbidden`	Key lacks the required scope or violates an origin/CIDR restriction	Correct key policy; do not retry unchanged
`not_found`	Resource is absent or the supplied receipt capability is invalid	Verify the identifier and capability
`rate_limited` or `quota_exceeded`	A project, key, IP, wallet, or action quota rejected the request	Wait for `retryAfterSeconds` when present
`invalid_request`	Input failed public validation	Correct the request; do not retry unchanged
`dependency_unavailable`	API or an upstream dependency could not serve the request	Retry with backoff when the operation is safe
`rpc_chain_mismatch`	A configured reader returned a different chain	Correct the RPC configuration immediately
`rpc_unavailable`	Configured RPC reads failed	Retry/fail over, or remove the reader to use bounded API preparation reads

The server can return additional stable lowercase codes for route-specific failures. Record requestId in diagnostics. Respect retryAfterSeconds instead of selecting a shorter delay.

Safe retries

Reads are safe to retry with bounded exponential backoff.
For an action or order submission, call submit() again on the same prepared object. It reuses the same signed envelope and idempotency key.
Do not call the prepare method again just to retry a transient submission failure; that creates a new nonce and idempotency key.
A duplicate intent receipt is an accepted replay of the same submission.
After an ambiguous timeout, query the returned receipt/status capability when available before creating a new action.
Fix configuration, authentication, scope, chain mismatch, and validation failures instead of retrying them.

Quota classes

Keys can grant read, realtime, and actions:submit scopes. Projects enforce separate budgets for indexed reads, live reads, realtime connection creation, and submissions. They can also cap pending actions, per-transaction sponsored gas, and daily sponsored gas. IP and wallet protections may be stricter than the project limit. Exact allocations belong to the issued project and key; the SDK does not assume universal numeric limits. On HTTP 429, inspect retryAfterSeconds and the response’s request ID. Realtime clients should let the built-in reconnect backoff obtain a fresh ticket rather than creating parallel subscriptions.

​Realtime, errors, and quotas

​Subscribe

​Error model

​Safe retries

​Quota classes

Realtime, errors, and quotas

Subscribe

Error model

Safe retries

Quota classes