henriqueatila/golang-gin-best-practices / skills/golang-gin-api
golang-gin-api
VerifiedBuild REST APIs with Go Gin. Use when creating Go web servers, adding Gin routes, writing handlers, or asking about middleware, binding, error handling, or project structure.
references/rate-limiting-headers.md
View on GitHub# Rate Limiting — Response Headers
See also: `rate-limiting-algorithms.md`, `rate-limiting-redis.md`, `rate-limiting-peruser.md`, `rate-limiting-tiered.md`, `rate-limiting-fallback.md`
## Response Headers
Set these on every response — not only on 429 — so clients can self-throttle before hitting the limit.
| Header | Value | When |
|---|---|---|
| `X-RateLimit-Limit` | Total requests allowed in window | Always |
| `X-RateLimit-Remaining` | Requests remaining this window | Always |
| `X-RateLimit-Reset` | Unix epoch when window resets | Always (where applicable) |
| `Retry-After` | Seconds until client may retry | 429 responses only |
```go
// pkg/middleware/rate_limit_headers.go
package middleware
import (
"net/http"
"strconv"
"time"
"github.com/gin-gonic/gin"
)
// SetRateLimitHeaders writes standard rate limit headers.
// resetAt: time when the current window expires (zero value omits X-RateLimit-Reset).
func SetRateLimitHeaders(c *gin.Context, limit, remaining int, resetAt time.Time) {
c.Header("X-RateLimit-Limit", strconv.Itoa(limit))
c.Header("X-RateLimit-Remaining", strconv.Itoa(remaining))
if !resetAt.IsZero() {
c.Header("X-RateLimit-Reset", strconv.FormatInt(resetAt.Unix(), 10))
}
}
// AbortRateLimited sends a 429 with Retry-After and standard rate limit headers.
func AbortRateLimited(c *gin.Context, limit int, retryAfterSec int) {
SetRateLimitHeaders(c, limit, 0, time.Now().Add(time.Duration(retryAfterSec)*time.Second))
c.Header("Retry-After", strconv.Itoa(retryAfterSec))
c.AbortWithStatusJSON(http.StatusTooManyRequests, gin.H{
"error": "rate limit exceeded",
"retry_after": retryAfterSec,
})
}
```
**Why always set headers:** Clients and API gateways use `X-RateLimit-Remaining` to implement proactive back-off. If headers only appear on 429, clients have no signal until they are already blocked.
Related skills
| Skill | Stars | Updated | Works with | Status | Install |
|---|---|---|---|---|---|
| receiving-code-reviewobra/superpowersUse when receiving code review feedback, before implementing suggestions, especially if feedback seems unclear or technically questionable - requires technical rigor and verification, not performative agreement or blind implementation | Stars: 322k | Updated | Claude CodeCodex | Verified | Install |
| requesting-code-reviewobra/superpowersUse when completing tasks, implementing major features, or before merging to verify work meets requirements | Stars: 322k | Updated | Claude CodeCodex | Verified | Install |
| using-git-worktreesobra/superpowersUse when starting feature work that needs isolation from current workspace or before executing implementation plans - ensures an isolated workspace exists via native tools or git worktree fallback | Stars: 322k | Updated | Claude CodeCodex | Verified | Install |
| verification-before-completionobra/superpowersUse when about to claim work is complete, fixed, or passing, before committing or creating PRs - requires running verification commands and confirming output before making any success claims; evidence before assertions always | Stars: 322k | Updated | Claude CodeCodex | Verified | Install |