ReferenceRate Limits

Rate Limits

Each key has a sustained rate and a burst. Requests spend units; the bucket refills continuously, so short spikes pass and steady overuse waits.

100 per second
200 burst

Quotas

Limits use GCRA, a token bucket without timers: a key may spend up to its burst at once, and earns one unit back every 1 / rate seconds. Defaults come from [limits]; any key can override them.

config.toml

[limits]
default_rate_per_sec = 100    # per key, sustained
default_burst = 200           # per key, at once
bulk_max_ips = 100            # addresses per bulk request

[[api_keys]]
name = "batch-jobs"
sha256 = "…"
rate_per_sec = 1000
burst = 5000

Limits reload live. A reload keeps the bucket of every key whose quota did not change, so editing one key never refills the others.

Costs

Request	Units
`GET /v1/lookup/{ip}`	1
`GET /v1/lookup/me`	1
`POST /v1/lookup`	1 per address, invalid ones included
`GET /v1/info`	1
`/healthz`, `/readyz`, `/metrics`	0

A request that fails validation after it was admitted still costs its units: a lookup of an invalid address costs 1.

Headers

Every admitted request reports the state of the key's bucket after it was charged.

HTTP/1.1 200 OK
ratelimit-limit: 200
ratelimit-remaining: 187
ratelimit-reset: 1

Header	Description
`RateLimit-Limit`	The key's burst: the most units it can hold.
`RateLimit-Remaining`	Units that can be spent right now.
`RateLimit-Reset`	Seconds until the bucket is full again, rounded up.
`Retry-After`	On `429 rate_limited` only: seconds to wait before the request would be admitted.

Other Limits

Limit	Applies to	Result
Failed authentication	Per client address: 10 at once, 30 per minute	`429 rate_limited`
Playground lookups	Per client address: 10 at once, 30 per minute	`429 rate_limited`
Requests in flight	Server: `server.max_inflight_requests` (4,096)	`503 overloaded`
Request deadline	Server: `server.request_timeout_ms` (5 s)	`503 timeout`
Open connections	Server: `server.max_connections` (10,000)	New connections wait in the kernel backlog
Request headers	16 KiB and 64 headers, complete within `server.header_read_timeout_ms` (5 s)	`431`, or the connection is closed

Client addresses group IPv6 per /64, the smallest block an end user gets.

Staying Within Limits

Batch addresses with Bulk Lookup: one round trip for up to 100 addresses at the same unit cost.
Watch RateLimit-Remaining and slow down before it reaches 0.
On 429 rate_limited, wait Retry-After seconds plus a little jitter. See Retrying.
Cache results. Databases change monthly, so an address's location is stable for days.