Rate limits

Encrata caps how many requests your account can make in a short window to keep the API fast and fair for everyone. This page explains the limit, the headers on every response, what a rejection looks like, and how to handle it.

How the limit works

Each account is limited to 200 requests per minute by default, on a rolling 1-minute window. The limit is enforced per account, not per API key. All of an account’s keys draw from the same budget, so creating extra keys does not raise your ceiling. It only helps you organize and revoke access.


Limit	200 requests / minute (default)
Scope	Per account (shared across all API keys)
Window	Rolling 1 minute
On exceed	`429 Too Many Requests`

Higher limits are available on some plans and on request. Contact support to raise your account’s limit.

Response headers

Every response carries the current state of your limit, so you can pace requests without guessing. Retry-After appears only on a 429.

Header	Meaning	Example
`X-RateLimit-Limit`	Maximum requests allowed per window	`200`
`X-RateLimit-Remaining`	Requests remaining in the current window	`173`
`X-RateLimit-Reset`	Unix timestamp (epoch seconds) when the window resets	`1727598000`
`Retry-After`	Seconds to wait before retrying	`12`

Retry off Retry-After, which is always a number of seconds to wait. X-RateLimit-Reset is an absolute Unix timestamp, not a delay. Sleeping for its value would pause your client for decades.

When you exceed the limit

Over the limit, the API responds with 429 Too Many Requests and this body:

{
  "error": "Rate limit exceeded. Please try again later."
}

Inspect the headers on any response with curl -i:

curl -i -X POST "https://developer.encrata.com/api/lookup/email/identity" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"email": "satya@microsoft.com"}'

A successful response reports the current limit state:

HTTP/1.1 200 OK
Content-Type: application/json
X-RateLimit-Limit: 200
X-RateLimit-Remaining: 173
X-RateLimit-Reset: 1727598000

Once the budget is spent, the same request returns a 429 with Retry-After:

HTTP/1.1 429 Too Many Requests
Content-Type: application/json
X-RateLimit-Limit: 200
X-RateLimit-Remaining: 0
X-RateLimit-Reset: 1727598000
Retry-After: 12

{"error": "Rate limit exceeded. Please try again later."}

Retry safely

When you get a 429, wait for Retry-After seconds, then retry. Cap the number of attempts so a client never loops forever:

import time
import requests

def lookup_with_retry(email, api_key, max_retries=3):
    url = "https://developer.encrata.com/api/lookup/email/identity"
    headers = {"Authorization": f"Bearer {api_key}"}

    for attempt in range(max_retries):
        resp = requests.post(url, headers=headers, json={"email": email})

        if resp.status_code == 429:
            retry_after = int(resp.headers.get("Retry-After", 2 ** attempt))
            time.sleep(retry_after)
            continue

        return resp.json()

    raise Exception("Max retries exceeded")

async function lookupWithRetry(email, apiKey, maxRetries = 3) {
  const url = "https://developer.encrata.com/api/lookup/email/identity";

  for (let attempt = 0; attempt < maxRetries; attempt++) {
    const resp = await fetch(url, {
      method: "POST",
      headers: {
        Authorization: `Bearer ${apiKey}`,
        "Content-Type": "application/json",
      },
      body: JSON.stringify({ email: email }),
    });

    if (resp.status === 429) {
      const retryAfter = parseInt(resp.headers.get("Retry-After") || 2 ** attempt, 10);
      await new Promise((r) => setTimeout(r, retryAfter * 1000));
      continue;
    }

    return resp.json();
  }

  throw new Error("Max retries exceeded");
}

func lookupWithRetry(email, apiKey string, maxRetries int) (map[string]interface{}, error) {
    url := "https://developer.encrata.com/api/lookup/email/identity"

    for attempt := 0; attempt < maxRetries; attempt++ {
        body, _ := json.Marshal(map[string]string{"email": email})
        req, _ := http.NewRequest("POST", url, bytes.NewBuffer(body))
        req.Header.Set("Authorization", "Bearer "+apiKey)
        req.Header.Set("Content-Type", "application/json")

        resp, err := http.DefaultClient.Do(req)
        if err != nil {
            return nil, err
        }
        defer resp.Body.Close()

        if resp.StatusCode == 429 {
            retryAfter, _ := strconv.Atoi(resp.Header.Get("Retry-After"))
            if retryAfter == 0 {
                retryAfter = 1 << attempt
            }
            time.Sleep(time.Duration(retryAfter) * time.Second)
            continue
        }

        var result map[string]interface{}
        json.NewDecoder(resp.Body).Decode(&result)
        return result, nil
    }

    return nil, fmt.Errorf("max retries exceeded")
}

Best practices

Honor Retry-After

Wait the Retry-After seconds before retrying, instead of a fixed delay.

Spread requests

Distribute calls evenly across the window rather than bursting.

Use bulk endpoints

For high-volume lookups, batch with bulk endpoints instead of single calls.

Watch remaining

Slow down when X-RateLimit-Remaining gets low, before you hit 429.

Next steps

Errors

Every status code and how to recover from it.

Bulk operations

Process large volumes without hitting per-request limits.

Overview

Configuration

Best practices

How the limit works

Response headers

When you exceed the limit

Retry safely

Best practices

Honor Retry-After

Spread requests

Use bulk endpoints

Watch remaining

Next steps

Errors

Bulk operations

​How the limit works

​Response headers

​When you exceed the limit

​Retry safely

​Best practices

Honor Retry-After

Spread requests

Use bulk endpoints

Watch remaining

​Next steps

Errors

Bulk operations

How the limit works

Response headers

When you exceed the limit

Retry safely

Best practices

Next steps