Rate Limits

Understand the rate limiting policies for the Whitepages Pro API, including monthly query limits and trial exhaustion.

The API enforces two different kinds of limit, and both return 429:

Rate limits bound how fast requests arrive. They clear on their own.
Usage caps bound how much you consume in a billing period. They persist until the period resets or you buy more queries.

Telling them apart matters, because retrying only helps for one of them.

Which 429 did I get?

Three responses share the 429 status — one rate limit and two usage caps. Each is identified by a single field in the body:

Identifying field	Kind	Meaning	What to do
`"message": "Too Many Requests"`	Rate limit	Too many requests per second	Back off and retry
`"message": "Limit Exceeded"`	Usage cap	Gateway quota for the period is out	Wait for the reset, or upgrade
`"error": "usage_cap_exceeded"`	Usage cap	Your plan's query allowance is out	Upgrade, or wait for the reset

Only the third sets error, so branching on its presence is the reliable check. The first two carry message and nothing else; the third carries the full set of fields below.

When you send requests too quickly, the API returns:

{
  "message": "Too Many Requests"
}

Wait before retrying, and implement exponential backoff in your application. Rate limits vary by plan; higher limits can be requested through support.

Usage caps

Every plan includes a query allowance for its billing period, and trial keys include a fixed trial allowance. When you exhaust it, the API returns a 429 with a structured body:

{
  "error": "usage_cap_exceeded",
  "error_instance_id": "1b9d6bcd-bbfd-4b2d-9b5d-ab8dfbbd4bed",
  "message": "Query cap reached for this billing cycle. To restore access before it resets, upgrade to a plan with more included queries: https://www.whitepages.com/billing/manage-plan/pro-api",
  "limit": 1000,
  "used": 1000,
  "reset_at": "2026-09-01T00:00:00+00:00",
  "upgrade_url": "https://www.whitepages.com/billing/manage-plan/pro-api"
}

Field	Meaning
`limit`	Billable queries your allowance covers for the current period
`used`	Billable queries consumed so far in the period
`reset_at`	When the allowance resets
`upgrade_url`	Where to restore access without waiting for the reset

upgrade_url differs by account type: paid subscribers are sent to their plan management page to move to a larger plan, and trials are sent to the pricing page to choose their first one.

Retrying will not clear a usage cap. Your allowance is spent until reset_at, or until you move to a plan with more included queries.

Response headers

usage_cap_exceeded responses carry the same numbers as headers, so you can react without parsing the body. The two gateway 429s do not set them:

Header	Meaning
`Retry-After`	Seconds until it is worth trying again
`X-RateLimit-Limit`	Same as `limit`
`X-RateLimit-Used`	Same as `used`
`X-RateLimit-Reset`	Same as `reset_at`

Retry-After is a re-check interval, not the time until your allowance returns. Access resumes once you have credit again — because the period reset, because you upgraded, or because support granted extra queries — and re-checking at that interval is how your key picks that up.

Best Practices

Implement retry logic with exponential backoff for rate-limit 429s
Branch on error so your integration does not retry a usage cap in a loop
Cache responses when appropriate to reduce API calls
Monitor usage via the Account Usage endpoint
Batch requests where possible to optimize your quota

Rate Limit Increases

For rate limit increases or quota adjustments, please contact our team at api@whitepages.com.

Billing

Understand how API usage is tracked and billed.

Retrieve usage data for a specific time range

Retrieve API usage data for a specified date range. Returns daily usage statistics including request counts for each day within the specified time period. The response includes both individual daily usage data and total usage for the entire period. - The request count is total number of requests made including 2xx, 4xx and 5xx responses. It is not the same as billable requests which is not available right now as part of API. - Maximum date range allowed: 90 days - Dates are in UTC format - Current day data when requested will be updated during the day - Usage data is updated approximately every 30 minutes - Usage data is returned only from the first date of actual usage in the specified duration

Purchasing the API

Step-by-step guide to purchasing a Whitepages Pro API subscription

Authentication

Learn how to authenticate your requests to the Whitepages Pro API.