Errors and retries

The Spectron SDKs expose typed errors so you can handle auth, scope, and not-found cases precisely. Retry policy is conservative: idempotent reads and remember / rememberMany / remember_many are retried automatically; other writes are not.

Python error hierarchy

from surrealdb import SpectronAPIError, SpectronAuthError, SpectronNotFoundError, SpectronScopeError

try:
    hits = memory.recall("what is my name?", scope=["user/alice"])
except SpectronAuthError as exc:
    print(exc.status_code, exc.message)
except SpectronScopeError as exc:
    print(exc.status_code, exc.message)
except SpectronNotFoundError as exc:
    print(exc.status_code, exc.message)
except SpectronAPIError as exc:
    print(exc.status_code, exc.message, exc.trace_id, exc.body)

Exception	HTTP	When it occurs
`SpectronError`	—	Base class
`SpectronAPIError`	Other non-2xx	Generic API failure; carries `status_code`, `message`, `trace_id`, `body`
`SpectronAuthError`	401	Missing or invalid API key
`SpectronScopeError`	403	Scope floor or principal rejects the call
`SpectronNotFoundError`	404	Context, session, document, or other resource not found

400, 422, 429, and 5xx responses that are not mapped to a subclass surface as SpectronAPIError. Inspect status_code and body (RFC 7807 problem details from the server) for validation and rate-limit details.

Async client: same exceptions; use AsyncSpectron and await each call.

JavaScript / TypeScript error hierarchy

import {
  AuthError,
  ConnectionError,
  NotFoundError,
  RateLimitError,
  ScopeError,
  ServerError,
  SpectronError,
  ValidationError,
} from "@surrealdb/spectron";

try {
  const hits = await client.recall("what is my name?", { scope: ["user/alice"] });
} catch (err) {
  if (err instanceof AuthError) { /* 401 */ }
  else if (err instanceof ScopeError) { /* 403 */ }
  else if (err instanceof NotFoundError) { /* 404 */ }
  else if (err instanceof ValidationError) { /* 400 / 422 */ }
  else if (err instanceof RateLimitError) {
    console.log(err.retryAfter);
  } else if (err instanceof ServerError) { /* 5xx after retries */ }
  else if (err instanceof ConnectionError) { /* network / timeout */ }
  else if (err instanceof SpectronError) { /* other */ }
}

Exception	HTTP	When it occurs
`SpectronError`	—	Base class
`AuthError`	401	Invalid or missing API key
`ScopeError`	403	Scope or principal denial
`NotFoundError`	404	Resource not found
`ValidationError`	400 / 422	Malformed request
`RateLimitError`	429	Rate or token budget exceeded (`retryAfter` when provided)
`ServerError`	5xx	Server error (retried for idempotent calls)
`ConnectionError`	—	Network failure or timeout

Retry policy

Both SDKs retry GET requests and remember / batch-remember writes (idempotent via Idempotency-Key) on connection errors and 5xx responses.

Request type	Auto-retry	Max attempts	Backoff
`GET`, idempotent reads	Yes	3 (default)	250ms, 500ms, 1000ms
`remember` / `rememberMany` / `remember_many`	Yes	3	Same
Other writes (`POST` upload, `forget`, …)	No	1	—

4xx responses are not retried.

Disabling or tuning retries

memory = Spectron(..., max_retries=0, timeout=10.0)

const client = new Spectron({ ..., maxRetries: 0, timeout: 10000 });

Timeouts

Default timeout: 30 seconds (Python) / 30,000 ms (JavaScript). Streaming chat disables read timeout on the connection while tokens arrive.

Rate limits in production

When the server returns 429, read retryAfter from the JavaScript RateLimitError or the problem-detail body in Python (SpectronAPIError.body) and back off before retrying manually. The SDK does not automatically retry 429 on writes.

Server error format

All Spectron HTTP errors follow RFC 7807 Problem Details. SDK exceptions wrap the decoded JSON where available.