go-retryablehttp

go-retryablehttp is a HashiCorp-maintained Go library that wraps the standard net/http client to add automatic retries with exponential backoff. It exposes nearly the same API as net/http, so it can be dropped into existing programs with minimal changes, while transparently retrying requests that fail due to connection errors or 5xx server responses (except 501 Not Implemented).

The library handles the tricky parts of making retries safe: it rewinds request bodies before each retry attempt via a pluggable ReaderFunc interface, supports converting a retryable Client into a standard *http.Client through a custom RoundTripper, and exposes hooks for logging, custom retry policies, custom backoff strategies, and request preparation before each retry. It’s used throughout HashiCorp’s own tooling (Vault, Consul, Terraform providers) and is a common dependency in Go services that need resilient outbound HTTP calls.

What You Get

• Drop-in net/http replacement - Client.Get/Post/Head mirror net/http’s package-level functions, so migration is largely a search-and-replace.
• Automatic exponential backoff - DefaultBackoff and LinearJitterBackoff give configurable wait strategies between retry attempts, including Retry-After header support for 429/503 responses.
• Safe body rewinding - Request wraps a ReaderFunc so POST/PUT bodies can be safely replayed across retries without manual buffering.
• StandardClient() bridge - Converts a *retryablehttp.Client into a *http.Client via a custom RoundTripper, so it works with any code that expects the standard client interface.
• Pluggable retry policy - CheckRetry, Backoff, ErrorHandler, and PrepareRetry are all overridable functions for custom retry logic.

Common Use Cases

• Calling flaky third-party APIs - wrap outbound HTTP calls to external services that occasionally return 5xx errors or drop connections.
• Building resilient internal service clients - internal microservices use it to tolerate transient network blips between services.
• Rate-limited API integrations - the built-in Retry-After header parsing makes it a natural fit for clients calling rate-limited REST APIs.
• HashiCorp ecosystem tooling - Vault, Consul, and various Terraform providers use it internally for their own outbound HTTP calls.

Under The Hood

Architecture The package is a single flat Go module with no internal subpackages: client.go holds the Client, Request, and retry loop, while roundtripper.go adds a RoundTripper adapter for stdlib compatibility. The core Do() method implements a manual retry loop driven entirely by pluggable function types (CheckRetry, Backoff, ErrorHandler, PrepareRetry) rather than interfaces or inheritance, which keeps the design lightweight and easy to override piecemeal. Data flows from a caller-constructed Request (an *http.Request plus a ReaderFunc body) through Do(), which calls CheckRetry after each attempt, computes wait time via Backoff, and finally defers to ErrorHandler once retries are exhausted. Because these extension points are threaded through function signatures rather than isolated behind an interface boundary, changing the core Do() loop or the ReaderFunc body abstraction would ripple through every consumer that relies on the default retry/backoff behavior.

Tech Stack Built for Go 1.23 with a minimal dependency footprint: hashicorp/go-cleanhttp supplies the pooled *http.Client used as the transport default, and hashicorp/go-hclog’s LeveledLogger interface is supported (without a hard import) for structured logging, pulling in fatih/color, mattn/go-colorable, mattn/go-isatty, and golang.org/x/sys as indirect dependencies. There is no database, web framework, or ORM involved — this is a foundational HTTP transport library. Linting runs through golangci-lint (errcheck, govet, staticcheck) via .golangci.yml, and GitHub Actions workflows (pr-unit-tests.yaml, pr-gofmt.yaml, actionlint.yml) gate formatting, unit tests, and workflow-file correctness on every change.

Code Quality Test coverage is extensive relative to the package’s size: client_test.go alone contains 28 test functions across roughly 1,400 lines, plus 4 more in roundtripper_test.go, covering retry policies, backoff calculations, body rewinding, and logger behavior. Error handling is explicit and layered — Do() tracks doErr, respErr, checkErr, and prepareErr as distinct values rather than collapsing them into one generic error. Naming follows idiomatic Go conventions (exported CamelCase types and functions, unexported lowercase internals), and the codebase is statically typed with no dynamic escape hatches. CI enforces both gofmt formatting and the unit test suite on every pull request.

API Design The public API is deliberately close to net/http’s shape: Client.Get/Post/Head/PostForm mirror the standard library’s package-level helpers almost exactly, which keeps the learning curve low for anyone already familiar with net/http. Getting started requires very little boilerplate — NewClient() followed by a direct call is enough for the common case — while advanced use (custom retry policy, custom logger, request preparation before retry) is opt-in through struct fields rather than required configuration. Documentation lives entirely in Go doc comments and the README rather than a dedicated docs site or example directory, which is adequate given the package’s small, focused surface area but leaves discovery of the less obvious hooks (PrepareRetry, ErrorHandler, ResponseLogHook) mostly up to reading the source.