Rate Limits

API usage is rate-limited to ensure system stability and fair usage across all customers.

Rate Limit Behavior

When you exceed the rate limit, the API returns a 429 Too Many Requests status code with retry information.

{
  "message": "Too Many Requests"
}

Monthly Query Limits & Trial Exhaustion

Your API plan includes a monthly query limit, and trial keys include a fixed trial allowance. When you exhaust either, the API returns:

{
  "message": "Limit Exceeded"
}

This Limit Exceeded response means you have used up your monthly query limit or your trial allowance. It is distinct from the 429 Too Many Requests response above: 429 is short-term throttling that clears on its own, while Limit Exceeded persists until your quota resets or you upgrade. You can either:

• Wait until the next month, when a plan's monthly limit resets
• Purchase a plan or additional queries, or contact support at api@whitepages.com
• If you are on a trial, purchase a plan to keep going once your trial allowance is exhausted

Best Practices

• Implement retry logic with exponential backoff for 429 responses
• 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.

Related