Rate Limits & Backoff

The Rate Limits page lists the per-endpoint limits. This guide explains the model and how to build a client that stays under it gracefully.

The token-bucket model#

Each API token has its own bucket. A limit of “60 / minute” means the bucket holds ~60 requests and refills steadily over the window. Send requests faster than the refill rate and the bucket empties; the next request gets 429 Too Many Requests with a Retry-After header telling you how many seconds until the bucket has room again.

Because buckets are per-token, you can parallelize across tokens but not around a single token's limit. Size your concurrency to the limit of the endpoint you're hitting.

Jittered exponential backoff#

On a 429, wait, then retry — but two rules matter: honor Retry-After when present, and add jitter so many clients (or many threads) don't retry in lockstep and re-collide (the “thundering herd”).

# cURL has no built-in backoff. In a shell, honor Retry-After:
url="https://api.cornect.io/api/v1/companies/search"
for attempt in 0 1 2 3 4; do
  code=$(curl -s -o /tmp/out -w "%{http_code}" -X POST "$url" \
    -H "Authorization: Bearer cornect_your_token_here" \
    -H "Content-Type: application/json" -d '{"query":"saas"}')
  [ "$code" != "429" ] && break
  sleep $(( (2 ** attempt) + RANDOM % 2 ))
done
cat /tmp/out

Common mistakes#

• Retrying immediately. A retry with no delay just burns another request and stays 429.
• Ignoring Retry-After. The server tells you exactly how long to wait — use it.
• No jitter. Synchronized retries re-collide. Always randomize.
• Unbounded retries. Cap attempts and surface a clear error rather than looping forever.
• Backing off on 4xx. Only 429 and 5xx are worth retrying; other 4xx won't fix themselves.