apix.spotzee.com.
The general rule’s tighter window is the one bursty traffic hits first. The 8,000-per-minute cap on
/api/client/* is the umbrella ceiling. Both rules count every request, authenticated or not.
Response on a block
Over-limit requests receive429 Too Many Requests with a Retry-After header and a JSON body matching the canonical Spotzee error envelope:
Retry strategy
1
Honour Retry-After first
Wait at least the number of seconds in
Retry-After before retrying. The block windows are short (10 seconds for the general rule), and the next attempt almost always succeeds.2
Add jitter when fanning out
If you’re driving many requests in parallel from a single host, add 0–500 ms of jitter on top of
Retry-After so retries don’t synchronise.3
Back off on repeats
If you see a second
429 after honouring Retry-After, double your delay (exponential backoff) up to a sensible cap, for example 60 seconds.4
Cap concurrency per IP
Both limits count by source IP. Outbound traffic from a single host is the one to pace.
Self-throttling example
Quota-metered endpoints
The Extended API charges credits on certain operations (validation, scoring, lookups, generation) on top of the per-IP rate limit. Hitting your credit balance returns402 quota_exceeded even when the rate-limit window shows capacity remaining. Inspect remaining credits via the Quota endpoints before high-volume runs.
Rolling out
Per-API-key sliding-window rate limits with a read/write split, anX-RateLimit-* header set, and a doubled budget for MCP traffic are wired in code and ship behind a feature flag. They are not active in production today. Once enabled, they will sit on top of the per-IP edge limits described above. The self-throttling pattern (honour Retry-After, add jitter, exponential backoff) works against either layer.
Next steps
Idempotency
Make retries safe.
Errors
Status codes and the
code catalogue.