Rate limits and retries

The idea

A real buyer should never notice the limits. A recruiter lists the people, or the clinics, nearest a place, a page at a time, the way a licensing board's own look-up shows them. What the limits stop is the pattern of copying the index: pages of a hundred, walking one search to its end, thousands of records a day, or a sweep across the whole map.

Limits

Per account, across the REST API, the MCP server, and the console together:

And across operations:

Days are UTC. A search area is a center point rounded to about a mile, so paging through one search, or changing its filters, is still one area. Free reference calls do not count toward the account limits.

GET /v2/usage returns the limits that apply to your account. If your work needs more, tell us what you are building.

Headers

Every metered response reports where you stand in the per-minute limit:

A 429 adds:

HTTP/1.1 429 Too Many Requests
Retry-After: 24
RateLimit-Limit: 30
RateLimit-Remaining: 0
RateLimit-Reset: 24

{ "error": { "code": "rate_limited", "message": "Too many source calls in a minute. Wait 24 seconds and retry.", "retry_after_seconds": 24, "request_id": "req_..." } }

Retrying

Wait as long as the server asks. When a response has Retry-After, wait that long. Do not retry sooner: it will fail again and count against you.

Otherwise, back off exponentially with jitter. For 500, 502, 503, 504 and network failures, wait a random time up to 0.5 seconds, then up to 1, then 2, then 4, capped at 8, and give up after five tries. The randomness matters: without it, every client that failed together retries together.

Make retries safe. Reads can always be repeated. To avoid paying twice for a call whose answer you never received, send an Idempotency-Key.

Do not retry what will not change. A 400, 401, 402, 403 or 404 will fail the same way. A daily limit (Retry-After measured in hours) is not something to sleep through in a request loop.

Working code for this is in the Quickstart.

Restrictions

Reaching a limit now and then is normal and costs nothing but the wait. Running into the limits repeatedly in a day is different: the account is restricted, and its metered calls return 403 account_restricted with a restricted_until time.

• The first restriction is short. A second is longer. After that, the account stays restricted until we lift it.
• A restricted account can still read its usage and manage its keys.
• We are alerted to every restriction. If yours is a mistake, contact us with the request_id and we will lift it.

We are told when an account trips a limit, when it reads an unusually large share of a day's allowance, and when many new accounts appear from one address. An account used to assemble a copy of the index can be closed.

What we record to do this

Enforcing these limits needs two things on each usage record: how many records the call returned, and a keyed fingerprint of the search area (the center, rounded to about a mile). The fingerprint exists to count distinct areas; the ZIP code and coordinates themselves are not stored. The names and license numbers you search are not recorded either. See Security.