errors & retries

The SDK throws two error types, and retries transient failures automatically. Both apply identically to tts.* and stt.* — same credentials, same retry policy, two hosts.

Error types

`GekoError`

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

import { GekoError } from "@gekoai/sdk";

try {
  await geko.tts.create({ text: "…" });
} catch (err) {
  if (err instanceof GekoError) {
    console.error(`Geko ${err.status}: ${err.detail}`);
  }
}

`GekoConnectionError`

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

import { GekoError, GekoConnectionError } from "@gekoai/sdk";

try {
  await geko.stt.transcribe({ audio });
} catch (err) {
  if (err instanceof GekoConnectionError) {
    console.error(err.timedOut ? "timed out" : "network error", err.cause);
  } else if (err instanceof GekoError) {
    console.error(`Geko ${err.status}: ${err.detail}`);
  } else {
    throw err;
  }
}

`TypeError`

Thrown before any request for argument mistakes the SDK can catch locally — stt.transcribe() with both audio and url (or neither), empty audio, or a negative estimateCredits() duration. These aren’t API errors and never count against your balance.

Status codes

Status	Meaning	Retried?
`400`	Bad request (empty `text`, unknown value, or `srt`/`vtt` on transcription).	No
`401`	Missing or invalid API key.	No
`404`	Unknown model or voice.	No
`413`	Audio longer than 2 hours — split it. Transcription only.	No
`429`	Out of credits — top up in the console.	No (a retry can’t create credits)
`408` `409` `500` `502` `503` `504`	Transient / server-side.	Yes
network / timeout	No response received.	Yes

429 applies to both products at once — it’s one balance, so synthesis and transcription stop together.

Automatic retries

On transient failures the SDK retries with exponential backoff + jitter (default 2 retries), honoring a Retry-After header when present.

const geko = new Geko({
  apiKey: process.env.GEKO_API_KEY,
  maxRetries: 2,     // 0 disables retries
  timeout: 120_000,  // per-request ms; 0 disables
});

Transcription uploads audio as an octet-stream rather than multipart, which keeps the request body replayable — so stt.transcribe() gets the same retry-on-5xx behavior as everything else. tts.stream() is the one exception: a partially consumed stream can’t be replayed, so streams are never retried. Bound them with a per-call timeout and cancel with an AbortSignal.

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:

const controller = new AbortController();
const audio = await geko.tts.create({
  text: "…",
  signal: controller.signal,
  timeout: 30_000,
});
// controller.abort() elsewhere to cancel

A user-triggered abort() propagates as-is (it is not retried or wrapped). A client-side timeout surfaces as a GekoConnectionError with timedOut === true.

Double-billing on a retried timeout. A tts.create() or stt.transcribe() call that times out client-side is retried by default. In the rare case the original request had already succeeded server-side, you could be billed twice. If you need strict once-only semantics, set maxRetries: 0 and handle retries yourself.

Next steps

Authentication

Fix a 401 by creating or rotating a key.

Limits & constraints

Request limits, formats, and cold starts.

Billing & credits

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

FAQ & troubleshooting

Common status codes and quick fixes.

get started

text-to-speech

speech-to-text

guides

sdk

reference

errors & retries

Error types

`GekoError`

`GekoConnectionError`

`TypeError`

Status codes

Automatic retries

Timeouts & cancellation

Next steps

Authentication

Limits & constraints

Billing & credits

FAQ & troubleshooting

​Error types

​GekoError

​GekoConnectionError

​TypeError

​Status codes

​Automatic retries

​Timeouts & cancellation

​Next steps

Authentication

Limits & constraints

Billing & credits

FAQ & troubleshooting

Error types

`GekoError`

`GekoConnectionError`

`TypeError`

Status codes

Automatic retries

Timeouts & cancellation

Next steps