Rate Limits

Rate limits control throughput: how many requests per second your account can make. They are separate from your monthly credits quota.

Limits by plan

Plan	Requests per second
Free	1
Pro 200k	5
Pro 500k	15
Pro 1.5M	25
Pro 3.5M	50
Enterprise	Custom

On the lookup and Gates endpoints, requests without a valid API key (missing, mistyped, or revoked) are limited to 5 per hour per IP. The lookup endpoints answer them without the fields your plan adds, and the Gates endpoints answer 401. After 5 in an hour, both return 429 with a Retry-After of up to an hour. If you get a 429 on your very first requests, check your API key.

The limit applies to your account as a whole. Every API key draws on the same limit, including keys belonging to different environments. Gates decisions share it with data API lookups, so a bulk lookup job or a staging load test can cause 429 responses on your production decisions.

The Gates Management API uses the same per-second rate, but with a counter of its own. Syncing rules never uses up the limit your decisions and lookups rely on.

Response headers

Header	Returned on	Description
X-RateLimit-Limit	Responses that were not rate limited	Requests allowed in the current window
X-RateLimit-Remaining	Responses that were not rate limited	Requests still available in the current window
Retry-After	Rate-limit 429 responses	Seconds to wait before the limit resets; temporary IP blocks may omit this header

Checking your limit

Your account's limit is returned by the status endpoint as account.plan.rate_limit:

curl -X GET "https://api.usercheck.com/status" \
  -H "Authorization: Bearer YOUR_API_KEY"

Exceeding the limit

Requests beyond your limit return 429 Too Many Requests:

{
  "status": 429,
  "error": "Too many requests"
}

Gates v1 endpoints return the same 429 in the Gates error envelope instead:

{
  "error": "rate_limit_exceeded",
  "message": "Too many requests"
}

These application rate-limit responses carry a Retry-After header giving the number of seconds until the limit resets. Pause requests for that interval, then resume at a lower rate.

Temporary IP blocks

Repeatedly ignoring 429 responses can temporarily block your IP at Cloudflare. A block triggered by requests with a valid API key typically lasts 5 minutes; one triggered by requests without a valid API key typically lasts 1 hour. The block applies to traffic from that IP, including other API keys sharing it.

The IP-block rule returns HTTP 429 with Content-Type: application/json and this body on the data API, Gates v0, and Gates v1:

{
  "error": "rate_limit_exceeded",
  "message": "Your IP is temporarily blocked after repeatedly exceeding rate limits. Pause requests before retrying."
}

IP blocks may omit Retry-After. Use the same retry policy as for throughput limits: pause requests, honor the header when present, and back off when it is absent. Match the error code, not the message wording.

Gates Management API rate limits do not create IP blocks, but management requests can still be blocked if their IP was blocked by other API traffic.

Monthly quota exhaustion

When your monthly credits run out, Gates v1 returns 429 quota_exceeded. The data API returns {"status":429,"error":"Too many requests"} and Gates v0 returns rate_limit_exceeded. Other 429 responses use those same bodies, so check your usage on the status endpoint if the cause is unclear. A missing Retry-After header alone does not identify quota exhaustion.