Retry Behavior Documentation

[Thomascountz]

This issue is to document the current retry behavior in case we want to change it in the future.

Current Behavior

The library implements a single-retry mechanism via lib/zendesk_api/middleware/request/retry.rb.

Retry Conditions

1. HTTP Status Codes (default: [429, 503], configurable via config.retry_codes):
2. Network Exceptions (opt-in via config.retry_on_exception = true, default: false):

Retry Strategy

• Exactly 1 retry per request
• Uses Retry-After response header when present, default: 10 seconds
• If the one-and-only retry fails, error propagates immediately
• Wait progress is logged linearly

Configuration

client = ZendeskAPI::Client.new do |config|
  config.retry = true                      # Default: false
  config.retry_codes = [429, 503, 502]    # Optional: customize codes
  config.retry_on_exception = true         # Optional: retry on network errors
end

Note: Setting config.retry = true automatically disables config.raise_error_when_rate_limited (mutually exclusive).

Request Flow

1. Initial request attempt
2. If 429/503/exception occurs:
   1. Sleep for Retry-After seconds (or 10s default)
   2. Retry once
3. Return final response or propagate error

References

• Implementation: lib/zendesk_api/middleware/request/retry.rb
• Middleware registration: lib/zendesk_api/client.rb:191-197