Ordering, bounds and errors

The error format, every published code, and which errors to retry.

The error format #

A stream reports a problem with an error event carrying code, message and a retryable boolean:

{"type":"error","code":"overload","message":"capacity","retryable":true,...}

An HTTP request reports the same fields inside an error object:

{"error":{"code":"overload","message":"capacity","retryable":true}}

Which errors to retry #

Read retryable from the response rather than from a table: true means the same request may succeed later, after a backoff; false means it will not change on its own. In general, overload and not-ready errors are retryable; validation and internal failures are not. Error messages never contain server file paths or model internals.

Streaming API codes #

• validation — the request was malformed or failed validation; not retryable.
• overload — the service is at capacity; retryable, so back off and retry.
• not_ready — the server has not finished starting; retryable.
• not_found — no such session (and, on the control plane, no such resource); not retryable.
• conflict — another live connection already holds the session (close 4409); not retryable.
• internal — an internal failure; not retryable.
• unauthorized — the key is missing, wrong or expired (401); not retryable.
• forbidden — the key is valid but lacks the scope (403, or close 4400 on /v1/stream); not retryable.
• quota_exhausted — the key's audio quota is used up; not retryable until more quota exists.

Playground and control-plane codes #

The service behind the playground and the dashboard returns code and message without retryable, so act on the HTTP status and any Retry-After header:

• origin_not_allowed — the request came from an origin the playground does not allow (403); not retryable.
• configuration_error — the playground configuration is invalid (500); not retryable.
• no_organization — the signed-in user has no organization (403); not retryable.
• playground_account_unverified — the account has no linked Google or GitHub identity (403); not retryable.
• playground_lifetime_exhausted — the account has used all of its free playground audio (403); not retryable.
• playground_grant_limit — the daily limit is reached (429, with Retry-After: 86400); retry after that.
• projection_failed — the key could not be issued (500); not retryable as it stands.
• bad_request — the request body or parameters are invalid (400); not retryable.
• rate_limited — too many requests from this address (429, with a Retry-After header); retry after that.

Delivery under load #

Audio is accepted whole or rejected; it is never silently dropped. A slow reader may receive fewer partials, merged together, but speaker, final, error and terminal events are kept. If your client stops reading for long enough, the service cancels the session.