RetryPolicy

controls automatic retries for the -with-retry entry points.

  • max-attempts: total tries including the first, so 1 never retries. One attempt is always made, so anything below 1 behaves as 1
  • base-delay-ms: how long to wait after the first failure
  • max-delay-ms: an upper bound on every delay, Retry-After included
  • honour-retry-after: whether a Retry-After response header replaces the computed delay
  • jitter: whether to draw each computed delay uniformly from [0, delay]
  • retryable-statuses: the HTTP status codes that deserve another attempt

Jitter is off by default so that delays are reproducible; turn it on when many clients share one provider and would otherwise retry in lockstep.

Build with RetryPolicy.default or RetryPolicy.none.

base-delay-ms

instantiate

(Fn [(Ref RetryPolicy a)] (Ref Int a))

gets the base-delay-ms property of a RetryPolicy.

copy

instantiate

(Fn [(Ref RetryPolicy a)] RetryPolicy)

copies a RetryPolicy.

default

defn

(Fn [] RetryPolicy) 

                        (default)

is a conservative policy: three attempts, 500ms of base delay doubling up to a 30s cap, honouring Retry-After, without jitter. It retries 429, the 500, 502, 503 and 504 server errors, and Anthropic's 529.

delay-for

defn

(Fn [(Ref RetryPolicy a), Int] Int) 

                        (delay-for p attempt)

returns the delay in milliseconds to wait before attempt, counting the first retry as attempt 1. Delays start at base-delay-ms and double per attempt, clamped to max-delay-ms.

delete

instantiate

(Fn [RetryPolicy] ())

deletes a RetryPolicy. Should usually not be called manually.

honour-retry-after

instantiate

(Fn [(Ref RetryPolicy a)] (Ref Bool a))

gets the honour-retry-after property of a RetryPolicy.

init

instantiate

(Fn [Int, Int, Int, Bool, Bool, (Array Int)] RetryPolicy)

creates a RetryPolicy.

jitter

instantiate

(Fn [(Ref RetryPolicy a)] (Ref Bool a))

gets the jitter property of a RetryPolicy.

jittered

defn

(Fn [(Ref RetryPolicy a), Int] Int) 

                        (jittered p ms)

draws a delay uniformly from [0, ms] if the policy asks for jitter, and returns ms unchanged otherwise.

max-attempts

instantiate

(Fn [(Ref RetryPolicy a)] (Ref Int a))

gets the max-attempts property of a RetryPolicy.

max-delay-ms

instantiate

(Fn [(Ref RetryPolicy a)] (Ref Int a))

gets the max-delay-ms property of a RetryPolicy.

none

defn

(Fn [] RetryPolicy) 

                        (none)

is a policy that never retries. It is what LLM.chat, LLM.chat-stream, LLM.chat-loop and LLM.embed use.

parse-retry-after

defn

(Fn [(Ref String a)] (Maybe Int)) 

                        (parse-retry-after value)

parses a Retry-After header value against the current time. See parse-retry-after-at.

parse-retry-after-at

defn

(Fn [(Ref String a), (Ref Datetime b)] (Maybe Int)) 

                        (parse-retry-after-at value now)

parses a Retry-After header value as of now, returning the number of seconds to wait.

Both forms of RFC 9110 ยง10.2.3 are understood: a non-negative delta-seconds count, and an HTTP-date, whose wait is measured from now and floored at zero. Anything else yields Nothing.

Leading zeros are part of delta-seconds and are read as written. A count larger than Int.MAX, and a date more than Int.MAX seconds ahead, both saturate at Int.MAX rather than reading as a short wait.

prn

instantiate

(Fn [(Ref RetryPolicy a)] String)

converts a RetryPolicy to a string.

retry-after-delay

defn

(Fn [(Ref RetryPolicy a), Int] Int) 

                        (retry-after-delay p secs)

converts a Retry-After wait of secs seconds into a delay in milliseconds, clamped to max-delay-ms so that a server cannot park a caller for arbitrarily long.

retryable-status?

defn

(Fn [(Ref RetryPolicy a), (Ref Int a)] Bool) 

                        (retryable-status? p code)

checks whether an HTTP status code deserves another attempt under p. Every status outside retryable-statuses, the remaining 4xx included, is reported to the caller unretried.

retryable-statuses

instantiate

(Fn [(Ref RetryPolicy a)] (Ref (Array Int) a))

gets the retryable-statuses property of a RetryPolicy.

retryable?

defn

(Fn [(Ref RetryPolicy a), (Ref LLMError a)] Bool) 

                        (retryable? p e)

checks whether an LLMError deserves another attempt under p. Transport failures do, unless they are a failure another attempt cannot change; API errors are judged by retryable-status?.

This is for callers holding an LLMError. The -with-retry entry points decide before an error exists, from the response status, and so reach for retryable-status? directly.

set-base-delay-ms

instantiate

(Fn [RetryPolicy, Int] RetryPolicy)

sets the base-delay-ms property of a RetryPolicy.

set-base-delay-ms!

instantiate

(Fn [(Ref RetryPolicy a), Int] ())

sets the base-delay-ms property of a RetryPolicy in place.

set-honour-retry-after

instantiate

(Fn [RetryPolicy, Bool] RetryPolicy)

sets the honour-retry-after property of a RetryPolicy.

set-honour-retry-after!

instantiate

(Fn [(Ref RetryPolicy a), Bool] ())

sets the honour-retry-after property of a RetryPolicy in place.

set-jitter

instantiate

(Fn [RetryPolicy, Bool] RetryPolicy)

sets the jitter property of a RetryPolicy.

set-jitter!

instantiate

(Fn [(Ref RetryPolicy a), Bool] ())

sets the jitter property of a RetryPolicy in place.

set-max-attempts

instantiate

(Fn [RetryPolicy, Int] RetryPolicy)

sets the max-attempts property of a RetryPolicy.

set-max-attempts!

instantiate

(Fn [(Ref RetryPolicy a), Int] ())

sets the max-attempts property of a RetryPolicy in place.

set-max-delay-ms

instantiate

(Fn [RetryPolicy, Int] RetryPolicy)

sets the max-delay-ms property of a RetryPolicy.

set-max-delay-ms!

instantiate

(Fn [(Ref RetryPolicy a), Int] ())

sets the max-delay-ms property of a RetryPolicy in place.

set-retryable-statuses

instantiate

(Fn [RetryPolicy, (Array Int)] RetryPolicy)

sets the retryable-statuses property of a RetryPolicy.

set-retryable-statuses!

instantiate

(Fn [(Ref RetryPolicy a), (Array Int)] ())

sets the retryable-statuses property of a RetryPolicy in place.

str

instantiate

(Fn [(Ref RetryPolicy a)] String)

converts a RetryPolicy to a string.

update-base-delay-ms

instantiate

(Fn [RetryPolicy, (Ref (Fn [Int] Int a) b)] RetryPolicy)

updates the base-delay-ms property of a RetryPolicy using a function f.

update-honour-retry-after

instantiate

(Fn [RetryPolicy, (Ref (Fn [Bool] Bool a) b)] RetryPolicy)

updates the honour-retry-after property of a RetryPolicy using a function f.

update-jitter

instantiate

(Fn [RetryPolicy, (Ref (Fn [Bool] Bool a) b)] RetryPolicy)

updates the jitter property of a RetryPolicy using a function f.

update-max-attempts

instantiate

(Fn [RetryPolicy, (Ref (Fn [Int] Int a) b)] RetryPolicy)

updates the max-attempts property of a RetryPolicy using a function f.

update-max-delay-ms

instantiate

(Fn [RetryPolicy, (Ref (Fn [Int] Int a) b)] RetryPolicy)

updates the max-delay-ms property of a RetryPolicy using a function f.

update-retryable-statuses

instantiate

(Fn [RetryPolicy, (Ref (Fn [(Array Int)] (Array Int) a) b)] RetryPolicy)

updates the retryable-statuses property of a RetryPolicy using a function f.