Retries & timeouts

Clients retry transient failures automatically, with exponential backoff and jitter. Tune it per-client at construction:

import { Client } from 'glotto-sdk';

const client = new Client({
  maxAttempts: 4,
  initialDelayMs: 200,
  maxDelayMs: 5000,
  jitter: true,
  timeoutMs: 30000,
});

What gets retried

By default the client retries safe requests — GET/HEAD — plus 5x responses, 429, and transport errors. Mutations are not retried blindly: a POST is retried only when idempotency is enabled (idempotency: true at construction — see Idempotency), so a retry can’t double-apply a write.

Configuring defaults

Set the defaults for everyone in glotto.yml#/client_settings/retry (max_attempts, initial_delay, max_delay, jitter); the constructor options above override them per-client.

Request timeouts

Each attempt is bounded by an overall request timeout. It defaults to 30 seconds, and client_settings.default_timeout sets a different spec-wide default — a duration string of the same grammar as the retry delays (60s, 500ms); a value outside that grammar, or a zero timeout, is rejected at validation. The generated client bakes the resolved value as its client-level default. Resolution runs from per-call → method → nearest resource → client instance → spec-wide client_settings → engine default. Configure resource and method preferences with default_request_options.

Every language exposes request controls through its native options, keyword arguments, context, or cancellation handle. The generated README shows your SDK’s spelling. A per-call retry limit counts retries after the initial attempt: zero makes one attempt. Request-specific headers and timeouts do not change the client defaults for later calls.

A buffered request’s timeout includes reading its response body. For SSE, NDJSON, and binary downloads, the timeout covers establishment through the first byte or an empty response. A WebSocket’s opening timeout ends at the successful upgrade. The established stream can outlive that timeout; caller cancellation and explicit closure remain active. An SDK does not reconnect or replay a stream after exposing its first byte.

Capping total retry time

max_attempts bounds how many tries happen; retry.max_elapsed bounds how long they take overall. Set it (a duration string, e.g. max_elapsed: 90s) and every SDK adds an overall wall-clock deadline spanning all attempts: before committing to a backoff wait, the client checks that the post-backoff resume time still fits the budget — if it doesn’t, the last response or error surfaces immediately, as if attempts were exhausted. The generated client exposes it as a constructor knob (maxElapsedMs in TypeScript/React Native/Dart, max_elapsed_ms/with_max_elapsed_ms in Python, Ruby, Elixir, and Rust, MaxElapsedMs in C#, maxElapsedMs in Java/Kotlin, $maxElapsedMs in PHP, maxElapsed seconds in Swift, WithMaxElapsed in Go), so a caller can still override the spec-wide default per client. Leave max_elapsed unset and no deadline applies — attempts and per-attempt timeouts are the only bounds, exactly as before.