How to Retry Failed Requests in Ruby
Learn safe, bounded retries in Ruby with Net::HTTP and Faraday, including idempotency, backoff, Retry-After, errors, testing, and production guidance.

Direct answer: use Net::HTTP#max_retries= when the standard library’s built-in handling of idempotent transport failures is enough. Use Faraday’s retry middleware when you need explicit status-code retries, backoff, jitter, Retry-After handling, or a policy shared across a Faraday application. Keep retries bounded, retry only operations that are safe to repeat, and return a clear failure when the budget is exhausted.
A timeout does not prove that the server did nothing. The server may have accepted a request while the client was waiting for a response. Retrying a non-idempotent operation such as a payment or order creation can therefore duplicate side effects. HTTP defines repeated PUT, DELETE, and safe methods as idempotent when they have the same intended effect as one request. RFC 9110 advises that a client should not automatically retry a non-idempotent request unless it can prove the operation is idempotent or detect that the original request was never applied. See RFC 9110, Section 9.2.2.
Choose a retry approach
| Requirement | Best fit | Reason |
|---|---|---|
| Only standard-library transport retries | Net::HTTP |
Smallest dependency and simple configuration. |
| Retry selected HTTP statuses such as 429 or 503 | Faraday retry middleware | Status selection and exception policy are configurable. |
| Backoff, jitter, maximum delay, or Retry-After | Faraday retry middleware | The middleware exposes these policy controls. |
| Existing Faraday client | Faraday retry middleware | Retry policy stays in the connection stack. |
| Non-idempotent POST | Application-level design | Use an idempotency key or another way to determine whether the original was applied before retrying. |
How retries work
A retry count is not the same as an attempt count. Two retries means one initial attempt plus two repeats, for up to three requests. Each retry should have a reason, such as a connection reset, read timeout, or an explicitly selected response status. Do not retry invalid input, authentication failures, or other permanent errors merely because they are exceptions.

Use exponential backoff so repeated failures do not create a tight loop. A conceptual schedule might start at 100 ms, multiply each delay by two, and cap it at a maximum. Jitter adds a small random amount so many workers do not reconnect at the same instant. These are configuration choices, not universal values.
Option 1: Net::HTTP built-in retries
Ruby’s Net::HTTP exposes max_retries=. The current documentation and Ruby 3.2 documentation describe an initial value of 1 and retries for idempotent requests after documented transport failures, including Net::ReadTimeout, IOError, EOFError, connection reset or abort errors, broken pipes, OpenSSL SSL errors, and Timeout::Error. Read the current Net::HTTP documentation and the Ruby 3.2 API documentation for the version you run.
require "net/http"
require "uri"
uri = URI("https://api.example.com/records/42")
http = Net::HTTP.new(uri.host, uri.port)
http.use_ssl = (uri.scheme == "https")
http.open_timeout = 5
http.read_timeout = 20
http.max_retries = 2
request = Net::HTTP::Get.new(uri)
request["Accept"] = "application/json"
begin
response = http.request(request)
puts "HTTP #{response.code}"
puts response.body
rescue Net::ReadTimeout, Timeout::Error, IOError, EOFError => e
warn "Request failed after retries: #{e.class}: #{e.message}"
raise
end
max_retries is a non-negative maximum retry setting. It is not a blanket retry for every HTTP status code. A response such as 500 or 429 is still a response; Net::HTTP’s built-in setting does not automatically apply a status policy to it. If your API uses transient response statuses, inspect the response and implement an explicit, bounded policy or use Faraday.
Manual Net::HTTP policy for selected statuses
When you need status retries but do not want another dependency, wrap the request in a loop. This example retries a safe GET on 429 and 503, honors a numeric Retry-After, and caps both attempts and delay.
require "net/http"
require "uri"
uri = URI("https://api.example.com/report")
max_retries = 2
base_delay = 0.2
max_delay = 3.0
retry_statuses = [429, 503]
attempt = 0
begin
attempt += 1
http = Net::HTTP.new(uri.host, uri.port)
http.use_ssl = (uri.scheme == "https")
http.open_timeout = 5
http.read_timeout = 20
request = Net::HTTP::Get.new(uri)
response = http.request(request)
if retry_statuses.include?(response.code.to_i) && attempt <= max_retries
retry_after = response["retry-after"]
delay = retry_after&.match?(/^\d+$/) ? retry_after.to_f : [base_delay * (2 ** (attempt - 1)), max_delay].min
sleep([delay, max_delay].min)
retry
end
raise "HTTP #{response.code}: #{response.body}" unless response.is_a?(Net::HTTPSuccess)
puts response.body
rescue Net::OpenTimeout, Net::ReadTimeout, EOFError, IOError, Errno::ECONNRESET => e
retry if attempt <= max_retries
warn "Exhausted #{max_retries} retries: #{e.class}"
raise
end
For production code, parse an HTTP-date form of Retry-After as well as seconds. RFC 9110 defines both forms and says the header tells the user agent how long to wait before a follow-up request. Never let a server-provided delay bypass your maximum.
Option 2: Faraday retry middleware
Faraday’s retry middleware defaults to two retries and documents default retryable exception and method behavior. Its default method list is GET, HEAD, OPTIONS, PUT, and DELETE. It supports retry statuses, exception selection, intervals, randomization, maximum intervals, backoff factors, and Retry-After handling. See the faraday-retry middleware source and verify option names against the version in your Gemfile.
# Gemfile
# gem "faraday"
# gem "faraday-retry"
require "faraday"
require "faraday/retry"
conn = Faraday.new("https://api.example.com") do |f|
f.request :retry,
max: 2,
interval: 0.1,
backoff_factor: 2,
max_interval: 2,
interval_randomness: 0.2,
retry_statuses: [429, 503]
f.response :raise_error
f.adapter Faraday.default_adapter
end
response = conn.get("/report")
puts response.status
puts response.body
The values above are an example policy. Adjust them to the remote service’s limits and your request latency budget. max: 2 means two retries after the first attempt. Restrict methods deliberately when adding non-default methods, and do not add POST unless the endpoint has idempotent semantics, an idempotency key, or a reliable way to determine whether the original was applied.
Faraday and Retry-After
The middleware can parse Retry-After and combine it with its interval, backoff, and maximum-delay settings. A server may send either seconds or an HTTP date. For a rate-limited API, honoring the server’s value is usually preferable to immediately starting another attempt, but still enforce a local upper bound so one response cannot stall a worker forever.
Safe retries for POST and other side effects
- Classify the operation. GET, HEAD, OPTIONS, PUT, and DELETE are generally idempotent by HTTP semantics, although application behavior still matters.
- Identify ambiguity. A timeout after sending bytes can mean the server committed the change.
- Use an idempotency key when supported. Send the same key on every attempt so the server can return the original result rather than creating another resource.
- Retry only with a bounded budget. Set a maximum number of retries and a maximum elapsed time.
- Make exhaustion explicit. Raise a typed error or return a result that tells the caller whether the outcome is unknown.

Reusable Ruby retry wrapper
class RetryExhausted < StandardError
attr_reader :attempts, :last_error
def initialize(attempts, last_error)
@attempts = attempts
@last_error = last_error
super("request failed after #{attempts} attempts: #{last_error.message}")
end
end
def with_retries(max_retries:, base_delay:, max_delay:, retryable:)
attempts = 0
begin
attempts += 1
return yield(attempts)
rescue *retryable => error
raise RetryExhausted.new(attempts, error) if attempts > max_retries
delay = [base_delay * (2 ** (attempts - 1)), max_delay].min
jitter = rand * (delay * 0.2)
sleep(delay + jitter)
retry
end
end
result = with_retries(
max_retries: 2,
base_delay: 0.1,
max_delay: 2.0,
retryable: [Net::ReadTimeout, Net::OpenTimeout, EOFError, IOError]
) do |attempt|
puts "attempt #{attempt}"
Net::HTTP.get_response(URI("https://api.example.com/health"))
end
puts result.code
Keep logging useful context such as host, method, attempt number, elapsed time, and final status. Do not log authorization headers, cookies, API keys, or sensitive request bodies. If you use a circuit breaker, stop creating new attempts while the dependency is known to be unhealthy.
Testing retry behavior
- Simulate a read timeout before a successful response and assert the number of attempts.
- Return 429 with both numeric and date-form
Retry-Aftervalues. - Return a permanent 400 or 401 and verify no retry occurs.
- Make the final attempt fail and assert that the caller receives a clear error.
- Test a POST whose response is lost after the server applies it; verify your idempotency-key or reconciliation path.
- Use a fake clock or injectable sleeper so tests do not wait in real time.
Performance, reliability, and cost considerations
Retries increase tail latency and request volume. A three-attempt policy can consume three connection slots and multiply load during an outage. Set connect and read timeouts separately, cap total elapsed time, and use jitter for fleets of workers. Reuse a Faraday connection or persistent Net::HTTP session where appropriate, but make sure stale connections are handled by your client version.
Retrying a 429 without respecting the server’s delay can extend an incident and trigger stricter limits. Retry only statuses that the API documents as transient. Cache safe, immutable responses when that is valid for your application; caching avoids both latency and retry traffic. Record attempts and final outcomes so you can distinguish successful first attempts, recovered failures, and exhausted operations.
Troubleshooting
| Symptom | Likely cause | Fix |
|---|---|---|
| Retries never happen for a 503 | Net::HTTP#max_retries= covers documented transport failures, not arbitrary statuses. |
Use an explicit status loop or Faraday retry_statuses. |
| A POST creates duplicates | The operation was retried after an ambiguous timeout. | Add an idempotency key or reconcile the original request before retrying. |
| Requests hammer the service | No backoff, jitter, or maximum delay. | Use exponential backoff, jitter, and a hard cap. |
| 429 responses keep failing | Retry-After is ignored or capped too low. |
Parse seconds and HTTP dates, then honor the value within a safe local maximum. |
| Faraday raises immediately | The middleware is absent, ordered incorrectly, or the exception/status is not configured. | Put f.request :retry in the connection, verify the installed faraday-retry version, and configure the required statuses or exceptions. |
| Authentication errors repeat | A broad rescue clause retries permanent failures. | Retry only the documented transient exceptions and statuses. |
| Worker stalls for minutes | Server-provided delay or repeated timeouts has no overall deadline. | Enforce per-attempt and total elapsed-time limits. |
Or skip the browser setup
If your Ruby job’s purpose is taking website screenshots, you can call ScreenshotNeo instead of maintaining browser automation and its retry edge cases. The API returns a clean PNG, JPEG, WebP, or PDF from one GET request. See the ScreenshotNeo API documentation for all options.
curl -G "https://api.screenshotneo.com/v1/shot" -d access_key=YOUR_API_KEY --data-urlencode url=https://stripe.com -o shot.webp
require "net/http"
require "uri"
uri = URI("https://api.screenshotneo.com/v1/shot?access_key=YOUR_API_KEY&url=https%3A%2F%2Fstripe.com")
response = Net::HTTP.get_response(uri)
raise "Screenshot failed: #{response.code}" unless response.is_a?(Net::HTTPSuccess)
File.binwrite("shot.webp", response.body)
import requests
r = requests.get("https://api.screenshotneo.com/v1/shot", params={"access_key": "YOUR_API_KEY", "url": "https://stripe.com"}, timeout=90)
open("shot.webp", "wb").write(r.content)
const q = new URLSearchParams({ access_key: 'YOUR_API_KEY', url: 'https://stripe.com' }); const res = await fetch(`https://api.screenshotneo.com/v1/shot?${q}`);
Cookie and consent banners, newsletter popups, and chat widgets are removed before the shot. Bot checks, blank pages, failed loads, timeouts, and cache hits are not billed, and response headers identify the page verdict and billing result. ScreenshotNeo also provides an MCP server for AI agents such as Claude and Cursor, with screenshot, page-info, and PDF tools. The Free plan includes 1,000 screenshots each month with no card; paid plans start at $5 for 3,000 shots. Create a free ScreenshotNeo account.
FAQ
Does Net::HTTP retry every exception?
No. Its built-in policy applies to documented idempotent transport and timeout failures. Check your Ruby version’s documentation.
Should I retry all 5xx responses?
No. Select statuses that the API documents as transient and consider the operation’s idempotency.
How many retries should I configure?
Use the smallest bounded number that fits your latency and recovery requirements. Treat example values as starting points, not published guarantees.
What happens when retries are exhausted?
Your code must decide. Raise or return a clear failure, preserve enough context for reconciliation, and tell callers when the outcome is unknown.
Can Retry-After be a date?
Yes. RFC 9110 permits either an HTTP date or a delay in seconds.


