Guides
Rate limits
Authenticated API requests are limited per API key and per account plan. Responses include rate-limit headers so clients can back off before they hit a hard limit.
How it works today
Each authenticated request consumes both an API-key bucket and an account bucket. The headers describe whichever has fewer requests left, and X-RateLimit-Policy names it. If either bucket is exhausted, the API returns 429 Too Many Requests with a Retry-After header.
Each API route also has a gateway allowance that every caller of that route shares: 100 requests a second with bursts up to 50, and 500 a second with bursts up to 1,000 on verification, the email finder, domain search, the job routes and GET /v1/account. Plan limits count a whole minute, so spread a minute's requests over the minute on any one route.
Plan limits
| Plan | Requests/minute |
|---|---|
| Free | 10 |
| Starter | 60 |
| Professional | 300 |
| Business | 1,000 |
| Enterprise | 5,000 |
Response headers
| Header | Meaning |
|---|---|
X-RateLimit-Limit | Requests allowed in the current window. |
X-RateLimit-Remaining | Requests remaining in the current window. |
X-RateLimit-Reset | Unix timestamp when the current window resets. |
X-RateLimit-Window | Window length in seconds. |
X-RateLimit-Policy | The whole policy in one header, e.g. 60;w=60;scope=api_key: limit, window, and the bucket the other headers describe. api_key is this key's own limit; user is the account's limit, which all of its keys share, so an account that uses several keys at once can see it. session and session_user are the same pair for a request signed in to the dashboard. A white-label sub-account's dashboard requests count against its user bucket. |
Retry-After | Seconds to wait after a 429 response. |
If you receive a 429
A 429 indicates the current key or account window is exhausted. Wait for the Retry-After value, then retry with jittered backoff if needed.
A 429 whose whole body is {"message":"Too Many Requests"}, with no error code, request ID or Retry-After header, comes from a route's gateway allowance. The gateway refused it before any Kawaa code ran, so nothing was charged and you can send the same request again unchanged. As there is no wait to read, wait about one second plus a random fraction of a second, double the wait after each further 429 from that route, and send to that route more slowly if they keep coming.
Best practices
Use batch endpoints
For verifying multiple emails, use /v1/verify/batch instead of making many individual requests.
Cache results
Keep the results you already have instead of verifying the same address again. Kawaa reuses a recent result for up to 24 hours at 0.5 credits, but that request still counts toward your rate limit, and inconclusive results (catch_all, risky, unknown, or a temporary outcome such as greylisting) are checked again at the full price.
Back off on 429
Retry with increasing, jittered delays rather than tight loops, so the platform can recover.
High-volume needs
Planning a high-volume integration? Talk to us so we can make sure you have the capacity and the right plan for your workload.
Contact sales