Errors and rate limits

On any failure, first preserve the signal, stop the affected work, and decide whether you know the outcome. Retry only when the operation is safe to repeat, the structured state permits it, and an app deadline remains.

1. Classify where the failure surfaced

A missing response isn't the same as retryable: true. A structured retryable: true is also not sufficient by itself: uploads and interrupted streams can remain unsafe or ambiguous to repeat.

2. Preserve HTTP and SDK fields

Protected Batch REST and realtime HTTP operations use the HTTP ErrorResponse shape:

This validated batch example means “fix the multipart body and don't retry it unchanged”:

{
  "error": "error.api.error.multipart.file.missing",
  "code": "VALIDATION_REQUIRED_FIELD",
  "detail": "error.api.error.multipart.file.missing",
  "retryable": false,
  "timestamp": "2026-01-15T10:30:00Z"
}

Always check the HTTP status before selecting a success parser. Preserve a raw body when structured parsing fails.

SDK 0.18.0 exposes different projections:

Still pre-validate TTS input before sending and always pass an explicit deadline (timeoutSeconds in JavaScript, timeout_seconds in Python). Read code and data from the global error callback before the request rejects; the generic exception keeps only the message.

3. Apply the decision table

A deployment gateway can return 429 for a Realtime HTTP request, while the current Fast/live backend can collapse an internal audio-capacity failure into retryable 500 with ASR_TRANSCRIPTION_FAILED. Do not infer a realtime quota, capacity pool, or reset window from either response or from Batch capacity.

4. Treat Batch 429 as capacity backpressure

Batch 429 includes the normal structured fields plus data.capacity:

{
  "error": "error.rate_limit",
  "code": "RATE_LIMIT_EXCEEDED",
  "detail": "error.rate_limit",
  "retryable": true,
  "timestamp": "2026-01-15T10:30:00Z",
  "data": { "capacity": 120.5 }
}

capacity is remaining capacity measured in audio seconds. Use it for queue and admission decisions. It is not a documented quota, reset window, or number of seconds to sleep.

The OpenAPI contract doesn't promise a Retry-After header. SDK retryAfter / retry_after is populated only when a valid header is actually present. If it is absent, apply capped exponential backoff with jitter. Always bound attempts, individual delays, total retry time, and producer concurrency with an overall deadline.

5. Preserve a Batch result before retrying its read

The released SDK doesn't retry batch calls. maxRetries / max_retries is deprecated, ignored, and retained only for compatibility. These tested fixtures retry getResult() / get_result(), not an upload, and explicitly pass saveResult: true / save_result=True. The default false can clear a terminal result after building the response, so a lost response can be followed by cleared. The preservation option makes bounded retry possible but does not define a retention duration. The fixtures use the released typed properties:

import {
  BatchTranscribeClient,
  BatchTranscribeError,
  BatchTranscribeRateLimitError,
  Language,
  type TranscriptionResponse,
} from '@humain-voice/sdk';

function requiredEnv(name: 'API_KEY' | 'API_URL'): string {
  const value = process.env[name];
  if (!value) throw new Error(`${name} is required`);
  return value;
}

async function pause(milliseconds: number): Promise<void> {
  await new Promise<void>((resolve) => setTimeout(resolve, milliseconds));
}

async function getResultWithRetry(
  client: BatchTranscribeClient,
  jobId: string,
  attempts = 5,
): Promise<TranscriptionResponse> {
  for (let attempt = 1; attempt <= attempts; attempt += 1) {
    try {
      // saveResult prevents a terminal read from clearing the stored result
      // before a retry. It does not establish a retention duration.
      return await client.getResult(jobId, Language.ArEn, { saveResult: true });
    } catch (error: unknown) {
      if (!(error instanceof BatchTranscribeError)) throw error;

      const rateLimited = error instanceof BatchTranscribeRateLimitError;
      const retryable = rateLimited || error.retryable === true;
      console.error({
        statusCode: error.statusCode,
        code: error.code,
        capacity: error.capacity,
      });
      if (!retryable || attempt === attempts) throw error;

      const serverDelayMs = rateLimited && error.retryAfter !== undefined
        ? error.retryAfter * 1_000
        : 0;
      const exponentialDelayMs = 500 * 2 ** (attempt - 1);
      await pause(Math.max(serverDelayMs, exponentialDelayMs) + Math.random() * 250);
    }
  }

  throw new Error('Retry loop exhausted');
}

async function main(): Promise<void> {
  const jobId = process.argv[2];
  if (!jobId) throw new Error('Pass a batch job ID as the first argument');

  const client = new BatchTranscribeClient({
    api_url: requiredEnv('API_URL'),
    api_key: requiredEnv('API_KEY'),
  });
  try {
    const result = await getResultWithRetry(client, jobId);
    console.info(result.status, result.results?.transcript ?? '');
  } finally {
    await client.close();
  }
}

void main().catch((error: unknown) => {
  console.error(error);
  process.exitCode = 1;
});

Expected behavior: retryable reads use at most five attempts, respect an actual retryAfter / retry_after value when present, add exponential delay and jitter, and rethrow the final failure. The attempt bound doesn't replace an overall app deadline.

6. Keep ambiguous operations out of automatic retry

Complete-file uploads

Batch job creation and fast complete-audio submission don't document an idempotency-key contract. A timeout or disconnect after bytes were sent doesn't prove either success or failure: the server may have accepted the request.

If a jobId or request UUID was returned, retain it and continue through that operation's normal result path. Without a conclusive response, record the ambiguous attempt and repeat only under an app policy that explicitly accepts duplicate work.

Realtime streams

The public Socket.IO and HTTP contracts define neither transparent resume nor idempotent frame replay. On an error or disconnect:

1. Stop sending audio and close the old stream or response.
2. Preserve committed results and discard unresolved provisional state.
3. Record the uncertain audio interval.
4. Reconnect with bounded backoff and a fresh UUID only if the error and app deadline permit it.
5. Keep the new stream separate until the app explicitly reconciles timelines.

Don't replay old frames or reuse the old UUID under an assumption of server-side deduplication.

7. Separate timeouts from the overall deadline

JavaScript TTS timeoutSeconds defaults to 30 seconds of inactivity while waiting for each audio chunk. Python TTS has no timeout unless timeout_seconds is supplied. Realtime ASR SDK close() waits only for protocol-level is_final, a routed error, or its close timeout and can return when that wait expires. None of these controls replaces the overall deadline.

After any expiry, clean up in finally: cancel HTTP reads and close response bodies; stop Socket.IO audio and call disconnect() or exit the Python async context; close the batch client. Don't infer that client cleanup canceled server-side work or in-flight TTS synthesis.

8. Log decisions and test the failure paths

Log the operation, transport, HTTP status or event name, code, retry decision, request or job UUID, attempt, deadline remaining, timeout type, and Batch capacity when present. Don't log API keys, full audio, or sensitive transcript text by default.

Next, run the safe-read fixture, then test invalid input, authentication, explicit 429, read timeout, ambiguous upload timeout, realtime disconnect, final-wait expiry, and cleanup in an isolated test environment.