Skip to main content
The SDK throws two error types, and retries transient failures automatically.

Error types

GekoError

The API responded with a non-2xx status. Carries the HTTP status and the server’s detail message.

GekoConnectionError

Extends GekoError (with status === 0). The request never reached the server — a network failure or a client-side timeout. Check timedOut and cause.

Status codes

Automatic retries

On transient failures the SDK retries with exponential backoff + jitter (default 2 retries), honoring a Retry-After header when present.
429 is deliberately not retried — it means you’re out of credits, which retrying won’t fix.

Timeouts & cancellation

The default timeout is 120 s (generous, because a scaled-to-zero GPU can cold-start slowly). Override per client or per call, and cancel with an AbortSignal:
A user-triggered abort() propagates as-is (it is not retried or wrapped). A client-side timeout surfaces as a GekoConnectionError with timedOut === true.
A tts.create() call that times out is retried by default. In the rare case a retry re-triggers a synthesis that had already succeeded server-side, you could be billed twice. If you need strict once-only semantics, set maxRetries: 0.

Next steps

Authentication

Fix a 401 by creating or rotating a key.

Limits & constraints

Request limits, output format, and cold starts.

Billing & credits

Why 429 means out of credits, and how to top up.

FAQ & troubleshooting

Common status codes and quick fixes.