Rate limits, burst limits, and quota error codes
Updated
Every metered response from CompliAPI includes standard rate-limit headers that tell you exactly where you stand in the current burst window. Rather than waiting for a 429 error, you can read these headers proactively and throttle your request rate to stay within limits.
Rate-limit response headers
Every metered response (and the free /search endpoint) carries the following headers, following the IETF draft RateLimit specification:
| Header | What it tells you |
|---|---|
RateLimit-Limit | The total number of requests allowed in the current window |
RateLimit-Remaining | How many requests are left in the window — already counting the current request |
RateLimit-Reset | Seconds until the current window resets |
RateLimit-Policy | The policy in <limit>;w=<window-seconds> form, for example 120;w=60 |
Understanding the two types of error responses
There are two distinct situations that stop a request from succeeding, and they return different status codes:
- Burst limit exceeded (
429) — you have sent too many requests too quickly within a short window. The response includes aRetry-Afterheader whose value is the number of seconds until the burst window resets. Wait that long, then retry. - Monthly quota exhausted (
402) — your organization has used all its credits for the billing period. The402response includes options to pay per request via x402 micropayments or to upgrade your plan. Unlike a burst429, theRetry-Afteron a monthly-quota402points at the period roll date — paying per request or upgrading resolves it sooner.
Tips for staying within limits
- Read
RateLimit-Remainingon every response so your integration can slow down before hitting a429, rather than reacting after the fact. - If your batch jobs risk exhausting the monthly quota, the
402response is designed to let you spill over into pay-per-request mode automatically rather than failing outright. - The free public endpoints (
/stats,/delisted,/screen/lists) are unauthenticated and not metered against your quota, though/searchis burst-limited per client IP. - Each metered request costs one credit regardless of how many source lists match or how many results are returned.