Rate limits

Limits protect the service and keep one noisy client from slowing the rest. They apply per API key, and rejected requests are never charged.

The limit

The default limit is 200 requests per 10 seconds per key. It is a token bucket: a key can burst up to 200 requests at once, and the allowance refills continuously across the window rather than resetting on the clock.

On top of that, an account can have at most 16 lookups running at once across all its keys. Cached results return immediately and do not count toward that cap.

Headers

Every authenticated response carries the state of the key's bucket:

Lookup responses also carry X-Request-Id, X-Credits-Charged and X-Credits-Remaining. A request with a bad key is rejected before the limiter, so a 401 has no rate limit headers.

When you hit the limit

The API answers HTTP 429 with the rate_limited error and a Retry-After header. Wait that many seconds, then retry. The error is retryable and nothing was charged.

1{
2  "error": {
3    "code": "rate_limited",
4    "message": "Too many requests for this API key.",
5    "fix": "Wait the number of seconds in the Retry-After header, then retry. Spread requests out to stay under the X-RateLimit-Limit value.",
6    "docs_url": "/docs/errors#rate_limited",
7    "retryable": true,
8    "request_id": "req_..."
9  }
10}

Retry with backoff

1async function lookup(path, body, attempts = 5) {
2  for (let attempt = 1; ; attempt += 1) {
3    const response = await fetch(`https://YOUR_API_HOST${path}`, {
4      method: "POST",
5      headers: {
6        Authorization: `Bearer ${process.env.LOOKVALID_API_KEY}`,
7        "Content-Type": "application/json",
8      },
9      body: JSON.stringify(body),
10    });
11    if (response.status !== 429 || attempt === attempts) return response;
12    const wait = Number(response.headers.get("Retry-After") ?? 1);
13    await new Promise((resolve) => setTimeout(resolve, wait * 1000));
14  }
15}

1import os
2import time
3import requests
4​
5def lookup(path, body, attempts=5):
6    for attempt in range(1, attempts + 1):
7        response = requests.post(
8            f"https://YOUR_API_HOST{path}",
9            headers={"Authorization": f"Bearer {os.environ['LOOKVALID_API_KEY']}"},
10            json=body,
11            timeout=30,
12        )
13        if response.status_code != 429 or attempt == attempts:
14            return response
15        time.sleep(float(response.headers.get("Retry-After", 1)))

Staying under the limit

• Spread bursts out instead of firing every request at once.
• Read X-RateLimit-Remaining and slow down before it reaches zero.
• Do not repeat lookups you already have: cached repeats are free in credits, but they still count toward the request limit.
• Higher limits are not self-serve yet. If you need more, email hello@lookvalid.com with your use case.