All WordPress HTML Templates Forms & Webhooks AI & Tools
Forms & Webhooks

Rate Limiting Your Form Endpoint Without Blocking Real Users

How to rate limit your API form endpoint with layered keys, token buckets and proper 429 responses, without blocking users behind NAT, VPNs or conference

A real working moment illustrating the theme of an article about rate limit api. Wide 16:9 banner, one strong focal point, magazine editorial quality, authentic and unstaged.

A client ran a webinar in March. Three hundred people on a university campus, all behind one NAT egress address, all filling in the same registration form inside a ten minute window. Our rate limiter did exactly what it was told: it let four through and returned 429 to everyone else. We found out from a support email the next morning.

That’s the failure mode nobody writes about. The listicles tell you to rate limit your API endpoint, give you a one line nginx snippet keyed on $binaryremoteaddr, and move on. The snippet works fine against a dumb script hammering your contact form from a single VPS. It also quietly blocks conference wifi, mobile carriers, corporate VPNs and anyone using iCloud Private Relay.

Good form rate limiting is less about the algorithm and more about what you count, what you do when the count is exceeded, and how many cheaper defences you put in front of it so the limiter almost never fires at a human.

Key Takeaways

  • Key on more than the IP. A layered key (IP plus browser-scoped token plus submitted email domain plus a global per-form ceiling) lets you keep tight limits without punishing shared egress addresses.
  • IPv4 at /32 and IPv6 at /64. Limiting a single IPv6 address is pointless because one client typically owns 18 quintillion of them; truncate to the /64 before you count.
  • Token bucket beats fixed window for forms. It absorbs legitimate bursts (a page with three forms, a double-click, a conference) while still enforcing a long run average. A fixed window lets through 2x the limit at the boundary.
  • Always return 429 with Retry-After, never 403, and never a bare 200. Returning 403 breaks client retry logic; returning 200 to a blocked human loses the lead silently.
  • Rate limit the side effects separately. Accepting the HTTP request is cheap, sending the email and writing to the CRM is not. Queue the work and throttle the expensive step with its own bucket.

Decide what you’re actually defending against

On a typical agency site contact form, genuine volume is tiny. A handful of submissions a day. Bot volume is an order of magnitude higher and arrives in distinct shapes:

  • Dumb form scrapers that POST once from a residential proxy and never come back. Volume per IP: one. No rate limit on earth catches these.
  • Loop scripts doing 50 to 500 POSTs a minute from one address. Trivially caught by any limiter.
  • Distributed spam from a proxy pool, one or two requests per IP, thousands of IPs. Only a global ceiling or content filtering catches these.
  • Resource abuse, where somebody found your endpoint triggers an outbound email per request and is using you as a free mail relay or an amplification vector against a third party.
  • Accidental self-inflicted load: a retry loop in your own frontend, a monitoring probe, a QA engineer with a load test script.

Only two of those five are solved by counting requests per IP. Worth sitting with before you spend a sprint on a limiter. The honeypot field and the timestamp check will remove more junk than the rate limiter will, for about twenty lines of code.

A real working moment that fits an article section about

Why keying on the IP alone keeps biting us

Shared egress is the norm now, not the exception. Mobile carriers run carrier-grade NAT, so tens of thousands of subscribers can share a handful of v4 addresses. Offices, schools, hotels and coworking spaces all funnel through one or two addresses. Apple’s Private Relay egresses through a pool of shared addresses that geolocate roughly to the user’s region. If your limit is “5 per IP per hour”, you have set a limit of 5 per hour for an entire company.

The inverse problem is IPv6. A residential connection is usually delegated a /56 or /64, and the client can pick a fresh source address for every single request. Count at /128 and your limiter is decorative. Truncate before counting:

map $remoteaddr $rlkey {
    # Group IPv6 clients by their /64 prefix (first four hextets).
    # Does not match :: compressed forms, which fall through to default.
    "~^(?<v6prefix>[0-9a-f]{1,4}:[0-9a-f]{1,4}:[0-9a-f]{1,4}:[0-9a-f]{1,4}):"  $v6prefix;
    default $remote_addr;
}

limitreqzone $rl_key zone=forms:10m rate=6r/m;
limitreqstatus 429;

location = /api/contact {
    limit_req zone=forms burst=4 nodelay;   # nodelay: reject immediately, do not queue
    proxypass http://appupstream;
}

Note the burst=4 nodelay. Without nodelay, nginx delays excess requests to smooth them to the configured rate, which means a user waits 10 seconds for a form response. Almost always wrong for interactive endpoints. And if you’re behind Cloudflare or any proxy, $remoteaddr is the proxy, so you need realipheader CF-Connecting-IP with a correct setrealipfrom list or you’ll be limiting the whole edge as one client.

Layer your keys instead of picking one

The pattern we’ve settled on runs four counters per submission and blocks if any one trips. Each has a different purpose and a different tolerance.

  1. Per client token, a random UUID set in a first-party cookie or localStorage on page load. Tightest limit: 3 submissions in 10 minutes. Trivial to bypass (a bot just drops the cookie), which is exactly why the limit can be tight. Humans keep their cookies; bots that discard them fall through to the slacker IP tier.
  2. Per IP or /64: looser, say 20 in 10 minutes. High enough that a campus or an office never notices, low enough to stop a loop script dead.
  3. Per submitted identity: hash of the lowercased email address, or the phone number. 2 per hour. This one catches the proxy-rotating spammer who keeps using the same throwaway address, and it costs nothing.
  4. Per form, globally: a ceiling on the whole endpoint, maybe 200 per hour on a site that genuinely gets 10. When this trips you don’t block, you alert and switch into a stricter mode: require a Turnstile token for the next hour. This is your only real defence against distributed spam.

A missing cookie should cost the request trust, not block it outright. Treat “no client token” as a signal that moves the request into a lower trust tier with a tighter IP limit. Privacy extensions and Safari’s storage partitioning will clear cookies for real users, so rejection on that basis alone will produce false positives.

Token bucket, and why the fixed window betrays you

A fixed window counter (INCR key, EXPIRE 600) is five lines and it’s what most people ship. The flaw: a client can send the full limit at 09:59:59 and the full limit again at 10:00:01. Your “20 per 10 minutes” is really 40 in two seconds. For a form that triggers emails, that matters.

Token bucket fixes it and gives you a free bonus: a mathematically exact Retry-After. Run it as a Redis Lua script so the read, refill and decrement are atomic:

-- KEYS[1] = bucket key
-- ARGV = capacity, refilltokenspersec, nowms, cost
local cap    = tonumber(ARGV[1])
local refill = tonumber(ARGV[2])
local now    = tonumber(ARGV[3])
local cost   = tonumber(ARGV[4])

local state  = redis.call('HMGET', KEYS[1], 't', 'ts')
local tokens = tonumber(state[1])
local ts     = tonumber(state[2])
if tokens == nil then tokens = cap; ts = now end

-- refill based on elapsed wall time, clamped to capacity
tokens = math.min(cap, tokens + ((now - ts) / 1000) * refill)

local allowed, retry = 0, 0
if tokens >= cost then
  tokens  = tokens - cost
  allowed = 1
else
  retry = math.ceil((cost - tokens) / refill)  -- seconds until one token is available
end

redis.call('HSET', KEYS[1], 't', tokens, 'ts', now)
-- expire once a full refill has definitely happened, so idle keys self-clean
redis.call('PEXPIRE', KEYS[1], math.ceil((cap / refill) * 1000) + 60000)

return { allowed, math.floor(tokens), retry }
import Redis from 'ioredis';
const redis = new Redis(process.env.REDIS_URL);
redis.defineCommand('takeToken', { numberOfKeys: 1, lua: TOKENBUCKETLUA });

const TIERS = [
  { key: c => rl:tok:${c.clientToken}, cap: 3,   refillPerSec: 3 / 600 },
  { key: c => rl:ip:${c.ipKey},        cap: 20,  refillPerSec: 20 / 600 },
  { key: c => rl:id:${c.emailHash},    cap: 2,   refillPerSec: 2 / 3600 },
  { key: c => rl:form:${c.formId},     cap: 200, refillPerSec: 200 / 3600 },
];

export async function check(ctx) {
  for (const tier of TIERS) {
    if (!tier.key(ctx)) continue;                       // tier not applicable
    const [ok, remaining, retry] =
      await redis.takeToken(tier.key(ctx), tier.cap, tier.refillPerSec, Date.now(), 1);
    if (!ok) return { allowed: false, retryAfter: retry, tier: tier.key(ctx) };
  }
  return { allowed: true };
}

One caveat that costs people real money: if Redis is down, decide deliberately whether you fail open or closed. For a contact form, fail open and log loudly. Losing a sales enquiry is worse than accepting an hour of spam. For a password reset endpoint, fail closed.

Where to rate limit your API: edge, proxy or application

You want all three, doing different jobs.

The edge (Cloudflare Rate Limiting rules, Fastly, a WAF) is the only layer that stops traffic before it costs you compute. Put a crude, generous rule here: 60 requests per minute per IP to /api/*, action “managed challenge” rather than block. It exists to absorb volumetric nonsense, not to make fine-grained decisions.

The proxy layer (the nginx snippet above) is your cheap backstop if the edge is bypassed, which happens whenever someone discovers your origin IP. Keep it loose and stupid.

The application is where the layered keys live, because it’s the only place that can see the submitted email, the form ID and your own trust signals. It’s also where you return useful headers and useful errors.

If you’re on a static site with no backend at all, this is a lot of machinery for a contact form. Hosted endpoints like WebForms do the throttling, spam scoring and delivery fan-out for you, and you POST straight from the browser. We use it on brochure sites precisely so there’s no Redis to babysit for a form that gets six submissions a week.

Respond like an API, not like a wall

Three rules we enforce in code review.

429, with Retry-After. Not 403 (that means “authenticated but forbidden” and no sane client retries it), not 503, not a redirect to a generic error page. Retry-After in seconds, per RFC 9110, is the one header every HTTP client already understands.

if (!result.allowed) {
  res.set({
    'Retry-After': String(result.retryAfter),
    // IETF draft structured field, plus the de facto X- headers most clients read
    'RateLimit': "forms";r=0;t=${result.retryAfter},
    'X-RateLimit-Limit': '20',
    'X-RateLimit-Remaining': '0',
  });
  return res.status(429).json({
    error: 'rate_limited',
    message: Too many submissions. Try again in ${result.retryAfter} seconds, or email us at [email protected].,
    retry_after: result.retryAfter,
  });
}

Always give a human an escape hatch. The error copy must contain a direct email address or phone number. A blocked lead who can still reach you is an inconvenience; a blocked lead staring at “Error 429” is lost revenue. We’ve had exactly one complaint about rate limiting since adding that sentence.

Consider accepting and dropping for known-bad traffic. If the honeypot is filled and the submission is obvious spam, returning 200 with a normal success page is often better than 429, because the spammer’s tooling gets no feedback signal to tune against. Reserve the honest 429 for traffic that might be human.

On the client, handle it properly instead of showing a generic failure:

const res = await fetch('/api/contact', { method: 'POST', body: data });

if (res.status === 429) {
  const wait = Number(res.headers.get('Retry-After') || 60);
  showNotice(Please wait ${wait}s before sending again.);
  disableSubmit(wait * 1000);     // actually disable the button for that long
  return;
}

Cheaper defences that mean you rarely need to throttle requests

Every one of these removes load before the limiter sees it, and none of them have false positives against conference wifi.

  • Honeypot field, hidden with CSS (not type="hidden", which bots skip) and named something plausible like company_url. Still catches a large share of naive bots in 2026.
  • Timestamp floor. Embed a signed render time in the form; reject anything submitted in under 2.5 seconds. Humans don’t read and complete a contact form that fast. Sign it with HMAC so it can’t be forged, the same primitive you’d use for webhook signature verification.
  • Payload dedupe. Hash the normalised body, store for 60 seconds, return the original success response on a repeat. This kills double-click duplicates, which otherwise look like abuse and eat tokens.
  • Cloudflare Turnstile as an escalation, not a default. Only require it when a tier is at 50 percent or the global ceiling tripped. Invisible mode for most users, interactive only for the suspicious ones.
  • Proof of work (a small WASM hashcash puzzle) is the fashionable option. We’ve shipped it twice and removed it once: it adds 200 to 900ms on low-end Android and buys you little against a determined attacker with cloud CPU. Use it on endpoints where the attacker’s economics matter, not on a contact form.

Pick thresholds from your own data, then watch them

Don’t guess the limits. Run the limiter in shadow mode for two weeks: evaluate every tier, log the decision, block nothing. Then look at the p99 of submissions per key over your window. Set the limit at roughly three times that. Our contact forms usually land around a p99 of 2 per client token per 10 minutes, which is how we arrived at a cap of 3.

After going live, the metric that matters is not “requests blocked”. It’s blocks that were probably human: a 429 on a request that had a valid signed timestamp, an empty honeypot, a plausible message body and a non-disposable email domain. That number should be close to zero. If it isn’t, your keys are wrong, not your thresholds.

Alert on two things: a spike in global rejections (you’re under attack or your frontend has a retry bug) and any single key hitting its ceiling repeatedly over hours. We surface both on the same internal dashboard we use for webhook delivery status, because the on-call question is identical: is the pipeline dropping things that matter?

Frequently Asked Questions

What’s a sensible rate limit for a contact form?

Start at 3 submissions per 10 minutes per browser token, 20 per 10 minutes per IP or IPv6 /64, and 2 per hour per submitted email address. Those numbers come from the fact that genuine contact forms see very low per-person volume, so the tight tier can be tight. Measure your own p99 in shadow mode before committing, and set limits at about three times it.

Should I rate limit at the CDN or in my application code?

Both, with different jobs. The CDN or WAF handles volumetric traffic cheaply with a crude per-IP rule and a challenge action, while the application runs the fine-grained layered keys because it’s the only layer that can see the email address, form ID and trust signals. The proxy in between is your backstop for when someone finds your origin IP.

How do I avoid blocking users behind corporate NAT or mobile carriers?

Make the IP tier deliberately loose (20 or more per window) and do the strict counting on a per-browser token stored in a first-party cookie. Shared egress means an IP can represent thousands of people, so it’s a poor identity. Treat a missing cookie as reduced trust that tightens the IP limit, not as an instant rejection.

Is a token bucket really better than a simple counter with an expiry?

Yes, for two concrete reasons. A fixed window lets a client send double your limit across the window boundary, and it can’t tell the client when to retry, so you end up guessing Retry-After. The token bucket gives you an exact retry time and smooths legitimate bursts without raising the long run average.

What status code should a rate limited form return?

429 Too Many Requests, with a Retry-After header in seconds and a JSON body containing a human-readable message plus an alternative contact route. Avoid 403, which implies a permanent authorisation failure and stops well-behaved clients retrying. The one exception: for traffic you’re confident is a bot, returning a normal 200 denies the attacker useful feedback.

If you only do one thing this week, add the signed timestamp floor and the payload dedupe. They take an afternoon, they have effectively zero false positive rate, and on most of the sites we’ve audited they remove more junk than the rate limiter was ever catching. Build the layered token bucket after that, run it in shadow mode first, and judge it on how many real humans it blocks, not on how many requests it rejects.

429 retry-after header form submission form rate limiting form rate limiting without blocking users honeypot and signed timestamp spam protection nginx limit_req burst nodelay form rate limit api endpoint per IP rate limiting behind CGNAT and IPv6 /64 token bucket rate limiter redis lua