Rate limits

Each account can send 60 requests per minute, shared across all of its API keys.

The window is a fixed calendar minute, starting at :00 seconds.
A batch request counts as one request, whether it has 1 item or 50. Batching is the fastest way to process large volumes: up to 3,000 predictions per minute.
Requests rejected by the rate limiter are not charged.

When you hit the limit

HTTP/1.1 429 Too Many Requests
Retry-After: 60

{ "error": { "code": "rate_limited" } }

Wait for the number of seconds in Retry-After, then continue. Because a rate-limited request never started a lookup, it is always safe to send again.

Three different 429s

Code	Meaning	Charged	What to do
`rate_limited`	You sent more than 60 requests this minute	No	Wait for `Retry-After`, then resend
`quota_exceeded`	Not enough credits	No	Top up, or wait for the monthly reset
`provider_rate_limited`	Finowl intelligence is at capacity	Yes	Wait for `Retry-After`. See Retries before resending

Staying under the limit

Use batches for gender predictions

One batch of 50 uses 1/60 of your per-minute limit, compared with 50/60 for 50 single requests.

Pace requests on the client

For bulk jobs, send at most one request per second from a single worker. That stays under the limit with room for your live traffic.

Cache results you can reuse

Breach results for the same email rarely change within a day, and a name’s prediction does not change at all. Caching saves both rate limit and credits.

Need a higher limit? Email support@finowl.co with your expected volume.

Get started

Core concepts

Guides

When you hit the limit

Three different 429s

Staying under the limit

​When you hit the limit

​Three different 429s

​Staying under the limit

When you hit the limit

Three different 429s

Staying under the limit