Skip to content
Package65 repository health

backoff

Exponential backoff and retry for Go, with a generic Retry function, typed errors, and RetryAfter support for rate-limited APIs.

Library Govv7.0.34,094 stars MIT License
go get github.com/cenkalti/backoff/v7
View source

Repository health

Pre-computed score based on development activity, maintenance, community, maturity, and trend momentum.How we score it →
Good
  • Development activity72
  • Maintenance28
  • Community60
  • Maturity60
  • Momentum40

Technical analysis

AI-assessed by reading the actual repository — architecture, code quality, innovation, and documentation.How we score it →
Good
  • Architecture82
  • Code quality88
  • Innovation55
  • Learning curve65

backoff is a Go library implementing the exponential backoff algorithm ported from Google’s HTTP Client Library for Java. It exposes a generic Retry[T any] function that wraps any fallible operation, retrying it with a randomized exponential delay until it succeeds, returns a permanent error, or a configurable limit is reached.

Version 7 layers on typed error introspection via *RetryError (carrying both the last operation error and the reason retrying stopped), a RetryAfter mechanism for honoring server-specified retry delays (e.g. HTTP 429 Retry-After headers), and independent limits for context cancellation, max tries, and max elapsed time — all implemented with zero external dependencies.

What You Get

  • Generic Retry[T any] function that retries any typed operation with exponential backoff, context support, max-tries and max-elapsed-time limits
  • *RetryError with LastErr and Cause fields, inspectable via errors.Is/errors.As or the AsRetryError helper
  • Permanent(err) to stop retrying immediately on non-transient errors
  • RetryAfter(duration, cause) to honor server-specified delays (e.g. HTTP 429 Retry-After) and reset the backoff schedule
  • Pluggable BackOff interface with ExponentialBackOff, ConstantBackOff, ZeroBackOff, and StopBackOff implementations
  • Ticker type for channel-based retry loops outside of Retry

Common Use Cases

  • Resilient HTTP clients - wrap outbound API calls in Retry so transient 5xx errors and network blips are retried automatically while 4xx client errors stop immediately via Permanent
  • Rate-limit-aware API integrations - return RetryAfter from an operation when a downstream service responds with a Retry-After header, so the client waits the server-requested duration before retrying
  • Bounded background job retries - combine WithMaxTries and WithMaxElapsedTime to cap how long a background task keeps retrying before giving up and surfacing a typed ErrExhausted or ErrMaxElapsedTime cause
  • Custom retry loops - use Ticker directly when you need a channel of retry ticks instead of a blocking Retry call, for integrating backoff timing into existing select-based control flow

Under The Hood

Architecture

The package is a flat, single-directory Go module with each file owning one concern: backoff.go defines the BackOff interface and the trivial ZeroBackOff/StopBackOff/ConstantBackOff policies, exponential.go implements ExponentialBackOff’s randomized-interval formula, retry.go layers the generic Retry[T any] orchestration (context handling, MaxTries, MaxElapsedTime, RetryAfter, Permanent) on top of any BackOff, error.go defines the RetryError/RetryAfterError error types and sentinel causes, and ticker.go/timer.go provide a channel-based alternative to Retry plus an internal timer abstraction that keeps the package testable without real sleeps. Nothing in Retry depends on ExponentialBackOff directly — it only requires the BackOff interface — so swapping in a custom policy changes no other code.

Tech Stack

The module (github.com/cenkalti/backoff/v7, go.mod targets Go 1.23) has zero third-party dependencies, relying entirely on the standard library: context for cancellation, errors for Is/As-based error chains, math/rand/v2 for jittered intervals, sync for the Ticker’s stop-once semantics, and time throughout. Retry’s use of Go generics (Operation[T any]) lets callers get back a strongly typed result instead of an any that needs a type assertion, a change introduced in the v5-v7 rewrites documented in CHANGELOG.md.

Code Quality

Testing is extensive and table-driven: retry_test.go alone runs to nearly 600 lines covering permanent errors, RetryAfter resets, context cancellation races, and max-tries/max-elapsed-time interactions, with additional dedicated suites for the ticker, exponential formula, and tries counter. Error handling is explicit and typed throughout — RetryError implements Unwrap() []error so both Cause and LastErr participate in errors.Is/errors.As chains — and naming is consistent with Go conventions. A GitHub Actions workflow (.github/workflows/go.yaml) runs the test suite in CI, and doc comments are dense enough to double as the package’s primary documentation.

What Makes It Unique

The library doesn’t reinvent exponential backoff — the algorithm is the well-known jittered-multiplicative one ported from Google’s Java HTTP client — but its v6/v7 API design is notably deliberate about failure introspection: every Retry failure surfaces through one RetryError type that separates “what failed” (LastErr) from “why retrying stopped” (Cause), and RetryAfter lets an operation hand the scheduler a server-dictated delay without abandoning the surrounding backoff state. The CHANGELOG shows this API was iterated through several breaking major versions specifically to make error handling less ambiguous, rather than adding new backoff algorithms.

Used by 18 apps in this directory

Every app whose dependencies include github.com/cenkalti/backoff/v7, nine to a page.

Showing 18 apps
TypeScript 82%AGPL 3.0

OpenStatus

9,249

Devops · Monitoring

Open-source status pages and uptime monitoring with global synthetic checks, monitoring-as-code, and AI agent integration via MCP.

App
Built with
  • TypeScript 82%
  • MDX 13%
Updated 2 weeks agoView details
Go 52%Apache 2.0

opencloud

6,291

File Storage

Open source file management and collaboration platform that keeps your data under your control, no database required.

App
Built with
  • Go 52%
  • Gherkin 33%
  • PHP 11%
Updated 2 weeks agoView details
Go 91%Apache 2.0

Ory Kratos

13,947

Authentication

API-first identity and user management that handles login, registration, MFA, and recovery so your application never has to.

App
Built with
  • Go 91%
Updated 3 months agoView details
Go 99%Apache 2.0

SpiceDB

7,202

Authentication · Databases · Security

An open source, Google Zanzibar-inspired authorization database that models permissions as relationships and evaluates fine-grained access checks at massive scale with single-digit millisecond latency.

App
Built with
  • Go 99%
Updated 2 weeks agoView details
Go 94%MIT

Traefik

65,483

Automation · Devops · Security

A cloud-native reverse proxy and load balancer that auto-configures itself from Docker, Kubernetes, and other orchestrators — zero manual routing required.

App
Built with
  • Go 94%
Updated 2 weeks agoView details
Go 98%Other

Tyk API Gateway

10,877

Developer Tools · Devops

Cloud-native, high-performance open-source API gateway for REST, GraphQL, gRPC, and TCP — built in Go since 2014 with no feature lockout.

App
Built with
  • Go 98%
Updated 2 weeks agoView details
Go 88%Apache 2.0

Uncloud

5,599

Devops

Deploy and scale containerised apps across any servers without Kubernetes or Swarm overhead

App
Built with
  • Go 88%
Updated 2 weeks agoView details
Go 97%BSD 3

Weaviate

16,940

Databases · Search

Open-source vector database combining semantic search, hybrid queries, RAG, and image search in a single cloud-native system built for production scale.

App
Built with
  • Go 97%
Updated 2 weeks agoView details
Go 97%BSD 3

Weaviate

16,940

Databases · Search

Open-source vector database combining semantic search, hybrid queries, RAG, and image search in a single cloud-native system built for production scale.

App
Built with
  • Go 97%
Updated 2 weeks agoView details

Join founders building with open source

Opinionated takes, migration guides, cost-saving tips, and insights from the open source ecosystem.

Subscribe on SubstackJoin 750+ subscribers