Rate Limiting
The API can cap how much one caller may do in a window. It ships uncapped, which is how the API has always behaved.
Where to find it
Architect Panel → Configuration:
- Site Settings — requests allowed per window, window length and counter resolution
Architect Panel → Integration & Connections:
- API Server — the request log, where throttling shows up
Architect Panel → Security:
- Blocked IP Addresses — where repeated failed authentication is handled instead
The three settings
- Requests allowed per window — ships at 0, meaning unlimited.
- Window length — ships at an hour.
- Counter resolution — ships at a minute.
Keyed on the API key, not the address
This is the design decision worth understanding. The allowance belongs to the key.
Several callers legitimately share an address — a partner behind one gateway, several services in one data centre, everything behind a corporate connection. If the limit were per address, one badly behaved caller would exhaust the allowance and take the others down with it, and the victims would have no idea why.
Per key, a runaway integration throttles itself and nobody else.
It counts successful requests
Not failures. Repeated failed authentication is a different problem and is already handled by address-level blocking, which is the right tool for it — you do not want an attacker able to exhaust a legitimate key's allowance by failing against it.
Counter resolution
How finely the sliding window is counted. A finer resolution is more accurate and writes more counter rows; it must divide into the window, and is corrected automatically if it does not. Leave it alone unless you have a reason.
Should you turn it on?
Unlimited is fine for a small number of known integrations you control. A limit earns its place when:
- Third parties you do not control have keys.
- An integration has previously misbehaved — a retry loop, a poll that got faster.
- You want a runaway caller to degrade rather than to take a database with it.
Set it generously
Look at the request log first and find what your busiest legitimate integration actually does in an hour, then set the limit well above it. A limit that occasionally catches normal traffic produces intermittent failures at the caller's end that are miserable to diagnose from the other side.
The purpose is to bound a runaway, not to ration ordinary use.
Tell integrators the limit
If third parties have keys, publish the number. A caller who knows the limit can pace themselves; one who does not will discover it as random failures and will assume your API is unreliable.
Watch for it in the log
When an integration reports intermittent problems, check whether it is hitting the limit before investigating anything else. It is a quick check and it explains a class of failure that otherwise looks like flakiness.
Worked example
An organisation with four partner integrations reviews a month of logs: the busiest averages 400 requests an hour, peaking near 900. The limit is set to 5,000 an hour — far above any legitimate use, low enough to stop a runaway. Each partner is told the figure. Six months later a partner's retry loop hits it, throttles, and affects nobody else.
Recommendations
- Set a limit once third parties hold keys.
- Base it on observed traffic, generously.
- Publish the limit to anyone with a key.
- Check the log for throttling before diagnosing flakiness.