Fix RateLimitError: code=429, message=rate limit exceeded in Echo

This error occurs when Echo's rate limiting middleware blocks a request that exceeds the configured rate, but the implementation lacks proper client identification, store cleanup, or informative response headers. Fix it by using a token-bucket limiter with per-IP tracking, adding Retry-After headers, and implementing a cleanup goroutine to prevent memory leaks.

Reading the Stack Trace

Here's what each line means:

• github.com/labstack/echo/v4/middleware.RateLimiterWithConfig.func1.1({0x1029e4f80, 0x14000226000}): Echo's rate limiter middleware at line 87 determines the client has exceeded the configured rate and rejects the request.
• echo: GET /api/search -> echo/middleware.RateLimiterWithConfig.func1 | 429: The middleware returns HTTP 429 Too Many Requests to the client.
• github.com/labstack/echo/v4.(*Echo).ServeHTTP(0x14000128680, {0x1029e4f80, 0x140001c40e0}, 0x140002b4000): Echo processes the request through the middleware chain where the rate limiter intercepts it.

Common Causes

e.Use(middleware.RateLimiter(middleware.NewRateLimiterMemoryStore(10)))
// No TTL or cleanup — memory grows with every unique IP

e.Use(middleware.RateLimiterWithConfig(middleware.RateLimiterConfig{
	Store: middleware.NewRateLimiterMemoryStore(10),
	// No DenyHandler — default response has no Retry-After
}))

// Single global limiter for all clients
var globalLimiter = rate.NewLimiter(10, 10)

func RateLimitMiddleware(next echo.HandlerFunc) echo.HandlerFunc {
	return func(c echo.Context) error {
		if !globalLimiter.Allow() {
			return c.JSON(429, "too many requests")
		}
		return next(c)
	}
}

The Fix

Configure the rate limiter with a memory store that includes expiration to prevent memory leaks. Use IdentifierExtractor for per-IP limiting and a custom DenyHandler that returns a structured 429 response with a Retry-After header.

e.Use(middleware.RateLimiter(middleware.NewRateLimiterMemoryStore(10)))

e.Use(middleware.RateLimiterWithConfig(middleware.RateLimiterConfig{
	Store: middleware.NewRateLimiterMemoryStoreWithConfig(
		middleware.RateLimiterMemoryStoreConfig{
			Rate:      10,
			Burst:     20,
			ExpiresIn: 3 * time.Minute,
		},
	),
	IdentifierExtractor: func(c echo.Context) (string, error) {
		return c.RealIP(), nil
	},
	DenyHandler: func(c echo.Context, identifier string, err error) error {
		c.Response().Header().Set("Retry-After", "60")
		return c.JSON(http.StatusTooManyRequests, map[string]string{
			"error":   "rate_limit_exceeded",
			"message": "Too many requests. Please retry after 60 seconds.",
		})
	},
}))

Testing the Fix

package main_test

import (
	"net/http"
	"net/http/httptest"
	"testing"

	"github.com/labstack/echo/v4"
	"github.com/stretchr/testify/assert"
)

func TestRateLimit_AllowsNormalTraffic(t *testing.T) {
	e := setupEchoWithRateLimit()

	req := httptest.NewRequest(http.MethodGet, "/api/search", nil)
	rec := httptest.NewRecorder()
	e.ServeHTTP(rec, req)

	assert.Equal(t, http.StatusOK, rec.Code)
}

func TestRateLimit_BlocksExcessTraffic(t *testing.T) {
	e := setupEchoWithRateLimit() // configured with rate=1, burst=1

	for i := 0; i < 5; i++ {
		req := httptest.NewRequest(http.MethodGet, "/api/search", nil)
		rec := httptest.NewRecorder()
		e.ServeHTTP(rec, req)
		if rec.Code == http.StatusTooManyRequests {
			assert.NotEmpty(t, rec.Header().Get("Retry-After"))
			assert.Contains(t, rec.Body.String(), "rate_limit_exceeded")
			return
		}
	}
	t.Fatal("expected rate limit to trigger")
}

Run your tests:

go test ./... -v

Pushing Through CI/CD

git checkout -b fix/echo-rate-limit-error,git add main.go,git commit -m "fix: configure per-IP rate limiting with Retry-After header and store cleanup",git push origin fix/echo-rate-limit-error

Your CI config should look something like this:

name: CI
on:
  pull_request:
    branches: [main]
jobs:
  test:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: actions/setup-go@v5
        with:
          go-version: '1.22'
      - run: go mod download
      - run: go vet ./...
      - run: go test ./... -race -coverprofile=coverage.out
      - run: go build ./...

The Full Manual Process: 18 Steps

Here's every step you just went through to fix this one bug:

1. Notice the error alert or see it in your monitoring tool
2. Open the error dashboard and read the stack trace
3. Identify the file and line number from the stack trace
4. Open your IDE and navigate to the file
5. Read the surrounding code to understand context
6. Reproduce the error locally
7. Identify the root cause
8. Write the fix
9. Run the test suite locally
10. Fix any failing tests
11. Write new tests covering the edge case
12. Run the full test suite again
13. Create a new git branch
14. Commit and push your changes
15. Open a pull request
16. Wait for code review
17. Merge and deploy to production
18. Monitor production to confirm the error is resolved

Total time: 30-60 minutes. For one bug.

go get github.com/bugstack/sdk

import "github.com/bugstack/sdk"

func init() {
  bugstack.Init(os.Getenv("BUGSTACK_API_KEY"))
}

Deploying the Fix (Manual Path)

1. Run go test ./... locally to confirm rate limiting works.
2. Open a pull request with the rate limiter config changes.
3. Wait for CI checks to pass on the PR.
4. Have a teammate review and approve the PR.
5. Merge to main and verify in staging.

Frequently Asked Questions