Skip to main content
The Spotzee API enforces per-source-IP rate limits at the edge today. Two rules apply across 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 receive 429 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 returns 402 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, an X-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.