Client configuration and errors

All clients use the public HTTP API and current identity permissions. They do not run models locally. Use a worker credential in an agent runtime and a separate operator/person credential only where required.

Python

Client(base_url: str, token: str, timeout: float = 20) is synchronous and dependency-free. base_url must be an HTTP(S) URL with a host and no embedded username. timeout is a per-call network timeout in seconds. Model-backed helpers use at least 40 seconds; wait(timeout=None, interval=1) has its own local polling deadline.

BeepgridError.code, .message and .status expose an API rejection. Catch BeepgridError for a definitive HTTP error and ordinary network exceptions for an unknown transport outcome. call retries transport failures up to three attempts only for GET or a write with a saved key. It does not automatically retry ordinary HTTP errors. Upload is not automatically retried.

from beepgrid import Client, BeepgridError
client = Client('http://localhost:4074', worker_token, timeout=20)
try:
    current = client.get_request(request_id)
except BeepgridError as error:
    if error.status in (403, 404):
        print('This request is not currently accessible.')
    else:
        raise

worker_token comes from your protected worker file; request_id comes from an accepted request. See the complete setup for a runnable program with those values.

TypeScript

new Client(baseURL, token, transport = fetch) accepts an injectable fetch implementation. baseURL is public and read-only. Public methods return promises except the async event iterator. Optional AbortSignal values stop local work; they never imply cancellation of a durable request.

Ordinary calls default to a 20-second abort timeout. Assistance helpers use their longer timeout path. call<T>(method, path, data?, options?) returns T; options include key, signal and minimal. Keyed/read calls can retry transport or incomplete JSON decoding, up to three attempts. A definitive HTTP error becomes BeepgridError with code and status; its inherited message is safe explanatory text. HTTP rejection is not automatically retried by ordinary calls.

Use the typed input/result declarations in the TypeScript type reference. Do not cast an unknown response to a narrower lifecycle state without checking it.

Go

beepgrid.New(baseURL, token) returns a *Client. beepgrid.Key() creates a new random operation key; save it with job state before issuing a write you may need to recover after restart.

Client field	Default	Meaning
BaseURL	Constructor argument	Engine URL
Token	Constructor argument	Current bearer credential; never log it
HTTP	Client with a 20-second timeout	Optional transport override
AssistanceTimeout	Zero means 40 seconds	Model-backed helper timeout; a shorter context still wins
MaxResponseBytes	Zero means 256 MiB	Upper bound on decoded JSON response bytes

Every network operation takes a context and returns a value plus error, or just error for acknowledgment-style operations. Use errors.As(err, &apiError) with *beepgrid.APIError to inspect Code, Message and Status; use context errors for local cancellation. Do decodes into your out pointer, or discards the result when out=nil. Reads and keyed writes can retry transport failures; arbitrary unkeyed writes cannot be assumed safe.

The Go type reference includes every exported data/configuration field and Message.AttentionFor is illustrated in chat usage.

Stable intent across retries

A generated key inside a helper makes retries within that call safe; it does not make a later fresh helper call recover the same operation. Persist and explicitly reuse the original key for an unknown result. A different body under the same key conflicts. A new key means new intent.

Worker loops and event streams have their own reconnect/backoff behavior. A permanent authentication denial must stop; otherwise a revoked credential could retry indefinitely. Ordinary conversation text, delivery acknowledgment and a final typed response are never interchangeable.

---

Read this page as Markdown