Colour

API rate limits

Know how many requests each token, address and sign-in can make a minute and how to recover from a 429.

For: Administrator
Hosting: Any hosting
Devices: All devices
Business: All businesses

Checked against Pop Street Dispatch 0.1.0

Limits keep one busy client from slowing everyone else. You will be able to size a client under the limits and recover when you reach one.

The limits #

Each limit counts requests in a sliding 60 second window.

Bucket	Limit a minute	Who it counts
Token	300	Each token or integration key
Network address	600	Each address, for signed-in calls
Public routes	120	Each address, for routes with no sign-in
Sign-in	20	Each address, across the sign-in calls
VIN look-up	30	Each token

Steps when you see 429 #

Read the error code. rate_limited means a request limit. locked means too many failed sign-ins.
Wait. rate_limited carries Retry-After: 60. The window slides, so requests free up as old ones age past 60 seconds.
Spread the work. Use POST /batch to send up to 20 writes in one request, and use updated_since and GET /sync instead of polling lists.
A board that needs live changes uses the WebSocket feed. See "The live board feed".

Good to know #

A refused request is never counted, so waiting is enough.
The VIN limit counts every request whose path is 11 to 17 letters or digits, before the check digit is read.
Behind a reverse proxy, the server sees the proxy's address for every caller, so all callers share one address bucket. Keep the server on the office network, or give the proxy a limit of its own.

Technical details

Counters live in memory, so a server restart clears them.
The failed-sign-in lockout is separate: 8 failures in 15 minutes. See "Signing in, tokens and lockout".

If something goes wrong #

A client always hits 300: check for a loop that polls.
The board shows delays: use the live feed.