SDK Rate Limits per Endpoint and Retries

Agents & LLMs: a Markdown version of this page is available by appending .md to the URL, and the full documentation index is at llms.txt.

BlitzAPI enforces a per-endpoint request-per-second limit that depends on your plan and is counted per account (all its API keys share it): 5 requests per second per endpoint on the free trial, 10 on Start, 25 on Scale, custom on Build Your Infra (see Pricing). The limit applies independently to each endpoint, so calls to /enrichment/email and /enrichment/phone run at the same time without competing for the same budget. Both SDKs handle this for you: a client-side limiter keeps your outgoing requests under the cap, and any 429 that still slips through is retried automatically. In most cases you don’t need to write any rate-limit handling yourself.

Find your limit

Your per-endpoint limit is on key_info(). Read it rather than hard-coding a number, so your code stays correct when you change plan.

info = client.account.key_info()
print(info.max_requests_per_seconds)   # your per-endpoint req/s limit

const info = await client.account.key_info();
console.log(info.max_requests_per_seconds);  // your per-endpoint req/s limit

Every metered /v2 response also reports live headroom in its fair_usage block, so you can watch the budget mid-run without a second call:

result = client.enrichment.email(person_linkedin_url="...")
if result.fair_usage and result.fair_usage.rate_limit:
    print(result.fair_usage.rate_limit.remaining_this_second)   # calls left this second

const result = await client.enrichment.email({ person_linkedin_url: "..." });
console.log(result.fair_usage?.rate_limit?.remaining_this_second); // calls left this second

See Authentication for the full key_info response.

Client-side rate limiting

Each client throttles its outgoing requests to rate_limit_rps (default 5) per endpoint: every endpoint path gets its own limiter, mirroring the API’s per-endpoint budget. In Python it’s a sliding window (at most N requests to a given endpoint in any rolling second); in TypeScript it’s a token bucket (admits at most N per second, per endpoint). A single client instance therefore stays under the API limit on every endpoint on its own, as long as rate_limit_rps doesn’t exceed your plan’s limit. Set it to None / null to disable.

client = BlitzAPI(rate_limit_rps=5.0)   # default; None to disable

const client = new BlitzAPI({ rate_limit_rps: 5 }); // default; null to disable

Reuse one client per process. The limiter lives on the client instance, so a single shared client keeps every endpoint’s calls under its limit. Start (10) and Scale (25) both allow more than the default of 5 requests per second per endpoint, so the default leaves throughput on the table: set rate_limit_rps to max_requests_per_seconds from your key to use the full budget.

Automatic retries

429 (rate limited) and 5xx (server errors) are retried automatically, up to max_retries (default 3). After a 429, both SDKs wait for the time in the Retry-After header (the API sends 1 second; 60 seconds if the header is missing, and Python waits at most 120 seconds). After a 5xx, both back off exponentially with jitter: 0.5 seconds, doubling on each attempt up to 8 seconds, plus a random 0 to 0.5 seconds. 400 / 401 / 402 / 404 / 422 / 423 are not retried; they raise immediately. If the retries are exhausted, the error surfaces as RateLimitError (429) or ServerError / APIStatusError (5xx).

from blitz_api import BlitzAPI, RateLimitError

client = BlitzAPI(max_retries=5)   # default 3

try:
    client.search.people(people={"job_level": ["VP"]})
except RateLimitError:
    ...   # still 429 after retries: back off and try again later

import { BlitzAPI, RateLimitError } from "blitz-api-js";

const client = new BlitzAPI({ max_retries: 5 }); // default 3

try {
  await client.search.people({ people: { job_level: ["VP"] } });
} catch (err) {
  if (err instanceof RateLimitError) {
    // still 429 after retries: back off and try again later
  }
}

Timeouts are not retried

Each method takes a per-call timeout (Python keyword arg; TypeScript options object as the last argument). Unlike 429/5xx, a read timeout is not retried: the server may already have processed the request and counted its records, so the SDK surfaces APITimeoutError immediately rather than risk counting them twice. Raise the per-call timeout for genuinely slow endpoints instead of relying on retries.

client.enrichment.email(person_linkedin_url="...", timeout=10.0)

await client.enrichment.email({ person_linkedin_url: "..." }, { timeout: 10 });

Running many workers

The limiter is per client instance (per process), and the API limit is per endpoint, shared by every API key of your account. If you fan the SDK out across multiple processes or workers that hit the same endpoint, even with different API keys of the same account, their combined rate can exceed that endpoint’s limit and you’ll see 429s. The retry path absorbs occasional ones, but for steady throughput divide rate_limit_rps across the workers sharing an endpoint (e.g. 5 workers all calling /enrichment/email on an account limited to 10 requests per second per endpoint → rate_limit_rps = 2 each). Workers calling different endpoints don’t compete: each endpoint has its own budget.

Next steps

Pagination

Stream results across pages and bound the records you pull with max_items.

Python error handling

The full exception hierarchy for blitz-api-py.

TypeScript error handling

The full exception hierarchy for blitz-api-js.

API reference

Request/response schemas and a try-it console.

​Find your limit

​Client-side rate limiting

​Automatic retries

​Timeouts are not retried

​Running many workers

​Next steps

Pagination

Python error handling

TypeScript error handling

API reference

Find your limit

Client-side rate limiting

Automatic retries

Timeouts are not retried

Running many workers

Next steps