Best practices

Build for bounded live state#

Create a stream immediately before capture, wait for first_frame_at_ms, renew the lease before four minutes, and delete it in a finally block. Treat publish, viewer, and customer-room tokens as credentials. Never log them, place them in URLs, or persist them longer than their job.

Use the smallest media selection#

Use one image frame when the question is about the current scene. Request a video segment only when temporal order matters, and set max_fps to the lowest cadence that preserves the event. This reduces latency, token usage, and provider-side media processing.

Preserve ownership and region#

Use the same bearer key for stream creation, status, preview, deletion, and any chat request that references the stream. A resource owned by another identity returns 404 rather than revealing its existence. If creation uses X-Hallikar-Region, send the same value on every lifecycle call.

Handle failure by class#

Do not retry 401, 403, or validation 422 responses without changing the request. Retry transient 429, 502, 503, and 504 responses with capped exponential backoff and jitter. A failed keepalive near expiry requires a new stream; do not assume the old publish token remains valid.