SDK · Reference

Errors & limits

Every failure is a typed error subclassing HeisenbergError. The API's own message is preserved, and each error carries the fields you need to branch and to get support.

Error types

AuthError	401	Missing or invalid token.
PlanError	403	Your plan doesn’t include this endpoint. Carries requiredPlan, endpoint, agentId, code.
NotFoundError	404	Unknown agent_id / endpoint.
RateLimitError	429	Too many requests. Carries retryAfter (seconds).
ValidationError	400 / 422	Bad request or params.
ApiError	5xx	Server error.
NetworkError	—	No HTTP response: DNS, connection, timeout, abort.

Every error also carries status, code, requestId, and raw (the parsed response body) — include requestId when contacting support.

Handling

TypeScript

import { PlanError, RateLimitError, AuthError } from 'heisenberg-ai';

try {
    const page = await hb.sports.closingLine(conditionId);
} catch (e) {
    if (e instanceof PlanError)       console.log('needs plan:', e.requiredPlan, e.code);
    else if (e instanceof AuthError)  console.log('bad token');
    else if (e instanceof RateLimitError) console.log('retry after', e.retryAfter, 's');
    else throw e;
}

Python

from heisenberg import PlanError, RateLimitError, AuthError

try:
    page = hb.sports.closing_line(condition_id).page()
except PlanError as e:
    print("needs plan:", e.required_plan, e.code)
except RateLimitError as e:
    print("retry after", e.retry_after, "s")
except AuthError:
    print("bad token")

Automatic retries

The client retries 429, 5xx, and transient network errors with exponential backoff (honoring retry-after), up to maxRetries (TS) / max_retries (Python), default 2. A RateLimitError / ApiError is only thrown after retries are exhausted. Auth, plan, validation, and not-found errors are not retried — they won't succeed on a retry.

Pagination limit

Page size is capped at 200 rows; values above are clamped. Use auto-pagination to read past one page: for await (…of hb.polymarket.trades(…)) (TS) / for … in hb.polymarket.trades(…) (Python), or .all().

Gated endpoints & quotas

Sport and audience endpoints require a subscription; without it they raise a PlanError. Check ahead with hb.requires(agentId) or hb.catalog(). Request quotas depend on your plan — see Pricing & Plans.