docs
Backend

Rate Limiting

Redis-backed, fixed-window, fails open.

Counted in Redis, per hour. The subject is the token when there is one and the address otherwise — mobile networks put thousands of people behind one address, so limiting everyone by IP would punish a whole carrier for one script.

BucketLimitSubject
Barcode look-up600/hrdevice or address
Alternatives600/hrdevice or address
Trending600/hrdevice or address
Text search200/hrdevice or address
Confirm a product60/hrdevice
Submit a label20/hrdevice
Profile / subscription / link writes60/hrdevice
Register a device10/hraddress
Dashboard login attempt20/hraddress
Dashboard password change20/hraccount
Dashboard registration10/hraddress
Crash report submission200/hraddress
Global backstop, every route3,000/hraddress

Over the limit returns 429. The counter is a fixed window, incremented and expired in one Lua call, so a process dying mid-sequence can't leave a key without a TTL and jam a subject out permanently.

Fails open

If Redis is unreachable, the request is allowed through and the failure is logged. This limiter exists to blunt abuse — taking the whole API down because the cache blinked is the worse outcome.

The global 3,000/hr-per-address backstop covers every route, including ones added later, so a flood at an endpoint nobody remembered to protect still costs something. /health* is exempt — limiting health checks would pull the service out of rotation under exactly the load the limit exists for.

TRUSTED_PROXY_HOPS

X-Forwarded-For is a list each proxy appends to — everything to the left of what your own proxies added was written by the caller. Reading the leftmost entry (the obvious thing to do) means a client sends X-Forwarded-For: <anything> and picks a fresh rate-limit bucket on every request.

TRUSTED_PROXY_HOPS is the number of proxies in front of this process. The real client is the entry that many places from the right — the address the outermost trusted proxy actually observed.

Get this exactly right

It defaults to 0, which ignores the header entirely and uses the socket's peer address (unforgeable). Count only hops that actually append to the header: nginx alone in front is 1; a CDN in front of that is 2; an L4/TCP load balancer doesn't append and doesn't count. Setting it higher than the truth is worse than leaving it at 0 — the surplus entries are attacker-supplied, and you'd be trusting them.

See Deployment for the real value this is set to in production, and why.

On this page