Skip to content


Switch branches/tags

Name already in use

A tag already exists with the provided branch name. Many Git commands accept both tag and branch names, so creating this branch may cause unexpected behavior. Are you sure you want to create this branch?

Latest commit


Git stats


Failed to load latest commit information.
Latest commit message
Commit time

Throttled Build Status Go Reference

Package throttled implements rate limiting using the generic cell rate algorithm to limit access to resources such as HTTP endpoints.

The 2.0.0 release made some major changes to the throttled API. If this change broke your code in problematic ways or you wish a feature of the old API had been retained, please open an issue. We don't guarantee any particular changes but would like to hear more about what our users need. Thanks!


Go Modules are required to use Throttled (check that there's a go.mod in your package's root). Import Throttled:

import (

Then any of the standard Go tooling like go build, go test, will find the package automatically.

You can also pull it into your project using go get:

go get -u

Upgrading from the pre-Modules version

The current /v2 of Throttled is perfectly compatible with the pre-Modules version of Throttled, but when upgrading, you'll have to add /v2 to your imports. Sorry about the churn, but because Throttled was already on its semantic version 2 by the time Go Modules came around, its tooling didn't play nice because it expects the major version in the path to match the major in its tags.


API documentation is available on


This example demonstrates the usage of HTTPLimiter for rate-limiting access to an http.Handler to 20 requests per path per minute with bursts of up to 5 additional requests:

package main

import (


func myHandlerFunc(w http.ResponseWriter, r *http.Request) {
	fmt.Fprintf(w, "Hello, world")

func main() {
	store, err := memstore.NewCtx(65536)
	if err != nil {

	quota := throttled.RateQuota{
		MaxRate:  throttled.PerMin(20),
		MaxBurst: 5,
	rateLimiter, err := throttled.NewGCRARateLimiterCtx(store, quota)
	if err != nil {

	httpRateLimiter := throttled.HTTPRateLimiterCtx{
		RateLimiter: rateLimiter,
		VaryBy:      &throttled.VaryBy{Path: true},

	handler := http.HandlerFunc(myHandlerFunc)
	http.ListenAndServe(":8080", httpRateLimiter.RateLimit(handler))

Upgrading to context.Context aware version of throttled

To upgrade to the new context.Context aware version of throttled, update the package to the latest version and replace the following function with their context-aware equivalent:

  • memstore.New => memstore.NewCtx
  • goredisstore.New => goredisstore.NewCtx
  • redigostore.New => redigostore.NewCtx
  • throttled.NewGCRARateLimiter => throttled.NewGCRARateLimiterCtx
  • throttled.HTTPRateLimiter => throttled.HTTPRateLimiterCtx

Please note that not all stores make use of the passed context.Context yet.

See throttled/gcra for a list of other projects related to rate limiting and GCRA.


  1. Update Please use semantic versioning and the existing conventions established in the file. Commit the changes with a message like Bump version to 2.2.0.
  2. Tag master with a new version prefixed with v. For example, v2.2.0.
  3. git push origin master --tags.
  4. Publish a new release on the releases page. Copy the body from the contents of for the version and follow other conventions from previous releases.


The BSD 3-clause license. Copyright (c) 2014 Martin Angers and contributors.


Package throttled implements rate limiting access to resources such as HTTP endpoints.







No packages published