Skip to main content

Rate limits

Your account or service configuration may allow a different rate. Contact API responses report the active limit in X-RateLimit-Limit. For higher throughput, contact sales to request an increased limit. All-you-can-eat includes unlimited contact and company retrieval at 0 credits. Request rates and per-request limits still apply on that plan.

Process a large list in one request

Rate limits count requests, rather than the number of records in a request. Use enrichment arrays, audience filters, file exports, or an email batch upload to process many records together.

Example: enrich a list of company domains

Put up to 10,000 domains in the domains array on a single Company Enrich request. You do not need ten calls containing 1,000 domains each. If you also send LinkedIn URLs or company RBIDs, the combined identifier limit is 10,000 after normalization and duplicate removal. Set your API key as REVENUEBASE_API_KEY. This small example uses the same request shape as a larger list:
PAYG company enrichment costs 1 credit per returned match; combining inputs reduces request count, rather than the per-record credit price. AYCE includes unlimited company retrieval for 0 credits. An unmatched identifier does not add a company-row charge. For a large email list, upload a file to Batch Email Verification instead of calling the real-time endpoint once per address. Save the returned process_id, poll the existing job every 5–10 seconds, and download the results when ready. The real-time limit is a request rate, rather than the batch job’s processing speed. See the email batch walkthrough for the upload, status, and download calls.

Retry a rate-limited request

When you exceed a limit, the API returns 429 Too Many Requests.
  • Honor Retry-After when present. Email Verification supplies this on a rate-limit response.
  • For Contact API, also read X-RateLimit-Reset and wait until that time.
  • If no retry header is available, use exponential backoff. Coordinate requests across workers sharing the same user.
  • After an export or email batch returns a job ID, poll that job. Repeating the upload or export-start request creates a new job and can incur additional charges.
This fallback example retries a real-time email request:

Track usage with response headers

Contact API responses include the following headers when rate limiting is active. These headers are not a contract for every RevenueBase API response; for a rate-limited Email Verification request, use Retry-After. Read X-RateLimit-Reset before retrying to avoid sending requests that will immediately fail.

Error codes

Parse a 422 Validation Error

Validation errors return a detail array identifying each failing field. This response was captured by submitting an empty JSON body to Email Verification on the local test API on October 13, 2026:
loc identifies where the problem is (e.g. ["body", "email"]), and msg tells you what’s wrong. Fix each entry in the array and retry.

Next steps