# Client configuration and errors

Constructor options, transport retries, cancellation and error handling for each SDK.

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.

```python
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](https://beepgrid.com/docs/sdks/python/tour.md) 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](https://beepgrid.com/docs/sdks/typescript/types.md). 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](https://beepgrid.com/docs/sdks/go/types.md) includes every exported data/configuration field and `Message.AttentionFor` is illustrated in [chat usage](https://beepgrid.com/docs/sdks/go/chats.md).

## 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.