Bound retries around reads. Different rules for webhook rehearsal.

Default Headless client behavior is one initial attempt plus two retries, with an 8-second timeout per attempt and a 5-second maximum delay.

HTTP client policy

Attempts and delays

Without Retry-After, delay ismin(100 × 2^attemptIndex, maxRetryAfterMs). With defaults, the client waits 100 ms before attempt two and 200 ms before attempt three. It adds no jitter.

Retry-After

• A non-negative finite numeric value accepted by JavaScript Number is interpreted as seconds, converted to milliseconds, rounded, and capped.
• An HTTP date is converted to a non-negative delay and capped.
• An invalid value is ignored and exponential delay is used.
• The parsed bounded value is available as error.retryAfterMs after failure.

Configure the policy

const casset = createCassetClient({
  baseUrl: "http://127.0.0.1:3000",
  timeoutMs: 5_000,
  maxRetries: 1,          // two total attempts
  maxRetryAfterMs: 2_000,
})

Set maxRetries: 0 to disable automatic retries. SetmaxRetryAfterMs: 0 to remove retry waits without removing attempts. There is no separate jitter switch because the implementation adds no jitter.

Worst-case duration

These bounds apply to the built-in fetch transport, which observes the per-attempt AbortSignal, plus normal scheduler overhead. A custom transport that ignores its signal can outlive timeoutMs, so the SDK cannot state a hard wall-clock bound for that transport.

Failures that never retry

• Malformed handles, invalid configuration, and invalid request IDs fail before transport.
• An external signal already aborted at an attempt boundary, 408, 425, 400–404, 422, and any envelope with retryable: false are terminal.
• The built-in retry sleep is not abort-aware. If cancellation happens during that delay, the client enters the next attempt with an already-aborted signal and then fails terminally; do not treat the signal as an immediate total-deadline timer.
• Malformed success bodies and request-ID mismatches are terminal contract failures.
• The client exposes GET only; there is no SDK write method to retry.

Application-level recovery

The SDK has already spent its retry budget when it throws. Do not immediately wrap every call in another tight loop. For interactive UI, show a retry control after a retryable error. For a background job, add a larger, independently bounded schedule and keep the same request ID only for one SDK call—not across unrelated jobs.

Idempotency expectations

Local sandbox webhook policy

• Maximum: three total attempts.
• Timeout: two seconds per attempt.
• Sandbox delay after a retryable failure: 25 ms after attempt one, then 50 ms after attempt two.
• The delay is deterministic and deliberately small for tests; it is not the HTTP client's exponential policy.

Replay and duplicate suppression

Replaying a sandbox webhook preserves the immutable event ID and exact event body, then creates a new delivery ID. The receiver validates the exact event contract before deduplication and reports whether the delivery/event pair was already received. Concurrent console replay with the same idempotency key resolves to one delivery result.

Webhook signature window

• The HMAC input is timestamp + "." + exactBody.
• The receiver verifies the exact bytes; adding a newline invalidates the signature.
• Signatures outside a five-minute window are rejected.
• The receiver reads at most 128 KiB of UTF-8 request data.