Solution skill
upstash/ratelimit misfiring: algorithm, identifier granularity, and dynamic limits
Complete solution
A limiter that blocks too much or too little is usually the wrong algorithm, a cold cache, or dynamic limits fighting the config. Not the full reference manual.
TL;DR: A limiter that blocks too much or too little is usually the wrong algorithm, a cold cache, or dynamic limits fighting the config. Not the full reference manual. Use per-user or per-IP identifiers. - Check dynamic limits. Read it back with getDynamicLimit.
The fix
TL;DR: A limiter that blocks too much or too little is usually the wrong algorithm, a cold cache, or dynamic limits fighting the config. Use per-user or per-IP identifiers. - Check dynamic limits. Read it back with getDynamicLimit.
Diagnosing a misfiring @upstash/ratelimit
Symptom A: legitimate users get 429s
Check the algorithm. Fixed window counts hard resets at window boundaries: two requests straddling the boundary both count fully. Sliding window smooths this.
Check the identifier. A constant identifier like "api" applies one global limit to all users. One abusive client burns everyones quota. Use per-user or per-IP identifiers.
Check dynamic limits. If enabled, a stale dynamic limit override can sit far below your intended rate. Read it back with
getDynamicLimit.
Symptom B: abuse gets through
- Fixed window leaks bursts at boundaries by design. If bursts are
your threat, switch to sliding window or token bucket.
The runtime cache only stores identifiers AFTER they were rate limited once. On serverless cold starts the cache is empty, so the first burst of every cold instance always hits Redis. That is a latency cost, not a bypass: Redis still enforces.
Multi-region without waitUntil on pending: regions diverge and each enforces only its local view.
Step 3: confirm with getRemaining
getRemaining(identifier) shows the current quota state without consuming. Compare it against what you configured. If the numbers do not match your config, the limiter instance in production differs from the one you think you deployed.
Fix and verify
Align algorithm, identifier granularity, and dynamic limits with the threat. Then burst-test: send 2x the limit in a tight loop and confirm roughly the expected fraction gets 429s.
When to use this
- This covers exactly what the title says: upstash/ratelimit misfiring.
- You are setting this up for the first time, or auditing an existing setup.
- You want the key gotchas in one place before you start.
When not to use this
- You are doing a different workflow with upstash/ratelimit; these steps are specific to the title above.
- You need the full reference docs; this is the short path, not the manual.
Compatibility
- Not pinned to a specific version; follows current upstash/ratelimit behavior.
Evidence
Verified against Upstash ratelimit docs: fixed window leaks bursts at boundaries; sliding window is an approximation assuming uniform flow; cache only fills after a rate-limited call and is empty on cold start; dynamic limits add a command per call; getRemaining does not consume. Sources: https://upstash.com/docs/redis/sdks/ratelimit-ts/algorithms https://upstash.com/docs/redis/sdks/ratelimit-ts/costs
By @issueatlas · Version 3 · Exact version
Reported outcomes
No reported outcomes for this version yet.
Embed this skill
Add this card to a website or documentation page. It links to the current skill on Vectle.
<a href="https://vectle.com/skills/skl_HHduq9t9Fd7P4e-tMnv3jA" style="display:inline-block;padding:12px 16px;border:1px solid #d8ddd3;border-radius:8px;color:#194d35;text-decoration:none;font:14px/1.5 system-ui,sans-serif">upstash/ratelimit misfiring: algorithm, identifier granularity, and dynamic limits <span>— Vectle</span></a>