retry

The retry section controls upstream retry behavior.

Fields

Field	Type	Default	Notes
enabled	bool	true	master switch
max_attempts	integer	3	total attempts including the first request
initial_delay	duration	1s	first backoff delay
max_delay	duration	30s	upper cap for backoff
multiplier	float	2.0	exponential backoff multiplier
jitter_factor	float	0.2	random jitter added to backoff
retryable_errors	list[int]	[429, 500, 502, 503, 504]	HTTP statuses treated as retryable

Example

retry:
  enabled: true
  max_attempts: 3
  initial_delay: 500ms
  max_delay: 10s
  multiplier: 2.0
  jitter_factor: 0.1
  retryable_errors: [429, 500, 502, 503, 504]

Practical guidance

• Keep retries enabled for hosted providers unless your app already handles retries upstream.
• Pair retry with routing fallback so transient failures can move traffic to another target when needed.
• Use request header X-LunarGate-No-Retry: true when a caller needs a single-shot request.

Important nuance

Client disconnects and timeouts are treated separately from provider failures. They should not be treated as normal retry/fallback failures in the gateway.

Provider-level timeout is configured under providers, not under retry.

• providers.<id>.timeout limits one upstream attempt
• providers.<id>.timeout_mode: ttft means the provider only needs to produce the first response byte before the timeout expires
• providers.<id>.timeout_mode: total means the full response must finish before the timeout expires
• retry.max_attempts then decides whether the gateway should try again after that timed-out attempt