https://github.com/lostisland/faraday-retry

Catches exceptions and retries each request a limited number of times
https://github.com/lostisland/faraday-retry

Keywords from Contributors

feature-flag crash-reporting activerecord rubygems feature-toggle feature rubocop static-analysis rspec mvc

Last synced: about 4 hours ago
JSON representation

Repository metadata

Catches exceptions and retries each request a limited number of times

Host: GitHub
URL: https://github.com/lostisland/faraday-retry
Owner: lostisland
License: mit
Created: 2021-12-31T12:17:16.000Z (about 4 years ago)
Default Branch: main
Last Pushed: 2026-02-26T07:40:07.000Z (5 days ago)
Last Synced: 2026-02-27T23:35:46.585Z (4 days ago)
Language: Ruby
Size: 81.1 KB
Stars: 95
Watchers: 2
Forks: 30
Open Issues: 3
Releases: 12
Metadata Files:
- Readme: README.md
- Changelog: CHANGELOG.md
- License: LICENSE.md

Faraday Retry

The Retry middleware automatically retries requests that fail due to intermittent client
or server errors (such as network hiccups).
By default, it retries 2 times and handles only timeout exceptions.
It can be configured with an arbitrary number of retries, a list of exceptions to handle,
a retry interval, a percentage of randomness to add to the retry interval, and a backoff factor.
The middleware can also handle the Retry-After
header automatically when configured with the right status codes (see below for an example).

Installation

Add this line to your application's Gemfile:

gem 'faraday-retry'

And then execute:

bundle install

Or install it yourself as:

gem install faraday-retry

Usage

This example will result in a first interval that is random between 0.05 and 0.075
and a second interval that is random between 0.1 and 0.125.

require 'faraday'
require 'faraday/retry'

retry_options = {
  max: 2,
  interval: 0.05,
  interval_randomness: 0.5,
  backoff_factor: 2
}

conn = Faraday.new(...) do |f|
  f.request :retry, retry_options
  #...
end

conn.get('/')

Control when the middleware will retry requests

By default, the Retry middleware will only retry idempotent methods and the most common network-related exceptions.
You can change this behaviour by providing the right option when adding the middleware to your connection.

Specify which methods will be retried

You can provide a methods option with a list of HTTP methods.
This will replace the default list of HTTP methods: delete, get, head, options, put.

retry_options = {
  methods: %i[get post]
}

Specify which exceptions should trigger a retry

You can provide an exceptions option with a list of exceptions that will replace
the default exceptions: Errno::ETIMEDOUT, Timeout::Error, Faraday::TimeoutError, Faraday::Error::RetriableResponse.
This can be particularly useful when combined with the RaiseError middleware.

retry_options = {
  exceptions: [Faraday::ResourceNotFound, Faraday::UnauthorizedError]
}

If you want to inherit default exceptions, do it this way.

retry_options = {
  exceptions: Faraday::Retry::Middleware::DEFAULT_EXCEPTIONS + [Faraday::ResourceNotFound, Faraday::UnauthorizedError]
}

Specify on which response statuses to retry

By default the Retry middleware will only retry the request if one of the expected exceptions arise.
However, you can specify a list of HTTP statuses you'd like to be retried. When you do so, the middleware will
check the response status code and will retry the request if included in the list.

retry_options = {
  retry_statuses: [401, 409]
}

Automatically handle the `Retry-After` and `RateLimit-Reset` headers

Some APIs, like the Slack API, will inform you when you reach their API limits by replying with a response status code of 429
and a response header of Retry-After containing a time in seconds. You should then only retry querying after the amount of time provided by the Retry-After header,
otherwise you won't get a response. Other APIs communicate their rate limits via the RateLimit-xxx headers
where RateLimit-Reset behaves similarly to the Retry-After.

You can automatically handle both headers and have Faraday pause and retry for the right amount of time by including the 429 status code in the retry statuses list:

retry_options = {
  retry_statuses: [429]
}

If you are working with an API which does not comply with the Rate Limit RFC you can specify custom headers to be used for retry and reset, as well as a block to parse the headers:

retry_options = {
  retry_statuses: [429],
  rate_limit_retry_header: 'x-rate-limit-retry-after',
  rate_limit_reset_header: 'x-rate-limit-reset',
  header_parser_block: ->(value) { Time.at(value.to_i).utc - Time.now.utc }
}

Specify a custom retry logic

You can also specify a custom retry logic with the retry_if option.
This option accepts a block that will receive the env object and the exception raised
and should decide if the code should retry still the action or not independent of the retry count.
This would be useful if the exception produced is non-recoverable or if the the HTTP method called is not idempotent.

NOTE: this option will only be used for methods that are not included in the methods option.
If you want this to apply to all HTTP methods, pass methods: [] as an additional option.

# Retries the request if response contains { success: false }
retry_options = {
  retry_if: -> (env, _exc) { env.body[:success] == 'false' }
}

Call a block on every retry

You can specify a proc object through the retry_block option that will be called before every retry.
There are many different applications for this feature, ranging from instrumentation to monitoring.

The block is passed keyword arguments with contextual information: Request environment, middleware options, current number of retries, exception, and amount of time we will wait before retrying. (retry_block is called before the wait time happens)

For example, you might want to keep track of the response statuses:

response_statuses = []
retry_options = {
  retry_block: -> (env:, options:, retry_count:, exception:, will_retry_in:) { response_statuses << env.status }
}

Call a block after retries have been exhausted

You can specify a lambda object through the exhausted_retries_block option that will be called after all retries are exhausted.
This block will be called once.

The block is passed keyword arguments with contextual information and passed your data:

Request environment,
exception,
middleware options
and your data.

In a lambda you can pass any logic for further work.

For example, you might want to update user by request query.

retry_options = {
  exhausted_retries_block: -> (user_id:, env:, exception:, options:) { User.find_by!(id: user_id).do_admin! }
}

Development

After checking out the repo, run bin/setup to install dependencies.

Then, run bin/test to run the tests.

To install this gem onto your local machine, run rake build.

Releasing a new version

To release a new version, make a commit with a message such as "Bumped to 0.0.2", and change the Unreleased heading in CHANGELOG.md to a heading like "0.0.2 (2022-01-01)", and then use GitHub Releases to author a release. A GitHub Actions workflow then publishes a new gem to RubyGems.org.

Contributing

Bug reports and pull requests are welcome on GitHub.

License

The gem is available as open source under the terms of the MIT License.

Owner metadata

Name: lostisland
Login: lostisland
Email:
Kind: organization
Description:
Website:
Location:
Twitter:
Company:
Icon url: https://avatars.githubusercontent.com/u/2613464?v=4
Repositories: 22
Last ynced at: 2024-03-25T19:32:01.094Z
Profile URL: https://github.com/lostisland

GitHub Events

Total

Release event: 4
Delete event: 6
Pull request event: 11
Fork event: 6
Issues event: 3
Watch event: 25
Issue comment event: 14
Push event: 9
Pull request review comment event: 15
Pull request review event: 17
Create event: 9

Last Year

Release event: 4
Delete event: 6
Pull request event: 10
Fork event: 5
Issues event: 3
Watch event: 14
Issue comment event: 14
Push event: 8
Pull request review event: 16
Pull request review comment event: 15
Create event: 9

Committers metadata

Last synced: 3 days ago

Total Commits: 75
Total Committers: 19
Avg Commits per committer: 3.947
Development Distribution Score (DDS): 0.52

Commits in past year: 22
Committers in past year: 9
Avg Commits per committer in past year: 2.444
Development Distribution Score (DDS) in past year: 0.682

Name	Email	Commits
Olle Jonsson	o**n@g**m	36
Matt	i****a	13
Berkovich	m**h@n**m	5
dependabot[bot]	4****]	3
Jonathan Rochkind	j**d@s**g	2
Max Prokopiev	m**v@g**m	2
mi-wada	m**d@g**m	2
Adif Sgaid	6****d	1
Brett Marx	b**x@s**m	1
Brooke McKim	b**m@g**m	1
Eugene Smentyna	d**a@g**m	1
Felipe Zavan	f**e@z**e	1
Gary Tou	g**y@g**m	1
Justin Littman	j**n@g**m	1
Mikhail Berkovich	4****3	1
Peter Goldstein	p**n@g**m	1
R Gibim	9****e	1
Taketo Takashima	t**3@g**m	1
m-nakamura145	m**5@g**m	1

Committer domains:

Issue and Pull Request metadata

Last synced: 5 days ago

Total issues: 17
Total pull requests: 39
Average time to close issues: about 1 month
Average time to close pull requests: 1 day
Total issue authors: 16
Total pull request authors: 21
Average comments per issue: 2.41
Average comments per pull request: 1.0
Merged pull request: 36
Bot issues: 0
Bot pull requests: 4

Past year issues: 3
Past year pull requests: 11
Past year average time to close issues: 2 days
Past year average time to close pull requests: 1 day
Past year issue authors: 3
Past year pull request authors: 9
Past year average comments per issue: 1.67
Past year average comments per pull request: 0.82
Past year merged pull request: 11
Past year bot issues: 0
Past year bot pull requests: 2

More stats: https://issues.ecosyste.ms/repositories/lookup?url=https://github.com/lostisland/faraday-retry

Top Issue Authors

kwent (2)
imkaka (1)
BuonOmo (1)
zalom (1)
Combos93 (1)
jcoyne (1)
jesseduffield (1)
kinkou (1)
justinlittman (1)
jimeh (1)
doutatsu (1)
choosen (1)
zavan (1)
andy-gorman (1)
johnhebron (1)

Top Pull Request Authors

olleolleolle (9)
iMacTia (5)
dependabot[bot] (4)
jrochkind (2)
bertm13 (2)
njoshi-mdsol (2)
djsmentya (1)
taketo1113 (1)
justinlittman (1)
m-nakamura145 (1)
adifsgaid (1)
garyhtou (1)
choosen (1)
Combos93 (1)
maxprokopiev (1)

Top Issue Labels

question (3)
documentation (1)
enhancement (1)

Top Pull Request Labels

dependencies (4)
github_actions (2)
enhancement (1)

Package metadata

Total packages: 6
Total downloads:
- rubygems: 684,660,577 total
Total docker downloads: 1,895,342,412
Total dependent packages: 113 (may contain duplicates)
Total dependent repositories: 11,981 (may contain duplicates)
Total versions: 38
Total maintainers: 1

gem.coop: faraday-retry

Catches exceptions and retries each request a limited number of times.

Homepage: https://github.com/lostisland/faraday-retry
Documentation: http://www.rubydoc.info/gems/faraday-retry/
Licenses: MIT
Latest release: 2.4.0 (published 2 months ago)
Last Synced: 2026-03-02T03:02:23.815Z (1 day ago)
Versions: 12
Dependent Packages: 0
Dependent Repositories: 0
Downloads: 342,412,837 Total
Docker Downloads: 947,671,206
Rankings:
- Dependent repos count: 0.0%
- Dependent packages count: 0.0%
- Average: 0.043%
- Downloads: 0.077%
- Docker downloads count: 0.097%
Maintainers (1)
- iMacTia

rubygems.org: faraday-retry