A RichAPI rate limit controls how fast your organization sends requests. The limit is a number of requests per second, it follows the credits that the organization buys in a month, and every API key in the organization shares it. A request over the limit returns status 429 with a Retry-After header, and it costs 0 credits.

What is the difference between a rate limit and a credit balance?

A rate limit controls speed. A credit balance controls volume. The two are separate limits, and they fail with different status codes.

Item	Rate limit	Credit balance
What it controls	How fast requests arrive	How much work the workspace buys
Unit	Requests per second	Credits
Source	The rate tier of the organization	Credits bought and credits granted
Status on failure	`429`	`402`
Credits charged on failure	0	0
How to recover	Wait, then send the request again	Buy more credits
Counted for	The whole organization, shared by every API key	The whole organization

A workspace with a large credit balance still sends at the rate of its tier. If the balance reaches zero, a workspace on the top tier still returns 402.

What are the RichAPI rate tiers?

RichAPI has four rate tiers. The tier comes from the credits that the organization buys inside one billing cycle. Every new organization starts on base.

Tier	Credits in the cycle	Requests per second	Burst limit in one second
`base`	0	1	2
`regular`	5,000 or more	5	10
`power`	25,000 or more	10	20
`enterprise`	100,000 or more	25	50

RichAPI applies the tier to every active API key in the organization, and all of them share it. The requests-per-second column is the rate to design a client around. The burst limit column is the exact ceiling that RichAPI counts against.

Which credits move an organization to a higher rate tier?

Two kinds of credit count toward the rate tier: credits bought with a card, and bonus credits granted by RichAPI. Trial credits do not count.

Credit type	Counts toward the rate tier?
A credit pack bought on the Plans & Billing page	Yes
An auto-reload purchase	Yes
A bonus granted by RichAPI	Yes
Trial credits	No

RichAPI counts only the credits of the current billing cycle. The billing cycle of the organization starts on its billing day each month.

RichAPI recomputes the tier at three moments: after Stripe confirms a purchase, after a refund, and at the start of each billing cycle. A refund lowers the counted credits and can lower the tier.

How to raise the rate tier of the organization

Read the tier table above and find the credit total of the tier that you want.
Select Plans & Billing in the sidebar of the workspace. Only an organization owner can buy credits.
Find the Buy Credits section.
Buy one pack, or several packs, that reach that total inside the current billing cycle.
Complete the Stripe payment.

RichAPI raises the tier as soon as Stripe confirms the payment. The new rate applies to the next request.

Read the Transaction History table on the Plans & Billing page to confirm the credits of the current cycle. A row with the type Purchase counts toward the tier. An auto-reload purchase also shows the type Purchase. A row with the type Trial does not count.

How does the burst allowance work?

RichAPI counts the requests of the whole organization, across all its API keys, inside each one-second window. The ceiling for that window is the burst limit. The burst limit is twice the requests-per-second figure of the tier.

An organization on the regular tier has a rate of 5 requests per second and a burst limit of 10. The organization can send 10 requests inside one second, across all its API keys. Request 11 in that same second returns 429.

The window resets every second. The burst allowance covers a short spike, not a sustained rate. Design a client around the requests-per-second figure, and let the burst allowance absorb timing jitter.

What does a 429 response look like?

A rate-limited request returns status 429. The response carries a Retry-After header and a short JSON body. RichAPI charges no credits and calls no data provider for that request.

HTTP/1.1 429 Too Many Requests
Content-Type: application/json
Retry-After: 1
X-Correlation-Id: req-3f9a2c1b7d4e4f0a9b8c6d5e4f3a2b1c
X-RateLimit-Limit: 5
X-RateLimit-Burst: 10
X-RateLimit-Scope: organization
X-RateLimit-Tier: regular

{
  "error": "Too Many Requests — your organization's regular tier allows 5 requests/second (burst 10). This limit is shared by every API key in the organization.",
  "code": "RATE_LIMITED",
  "tier": "regular",
  "limit_req_per_sec": 5,
  "burst_limit": 10
}

Status: 429
Retry-After header: 1. The one-second window resets after one second.
X-Correlation-Id header: the request ID, in the form req- and 32 hexadecimal characters. Quote it in a support message.
X-RateLimit-Limit and X-RateLimit-Burst headers: the requests per second and the burst limit of the organization.
X-RateLimit-Scope header: always organization.
X-RateLimit-Tier header: the rate tier of the organization.
Body: error, code with the value RATE_LIMITED, tier, limit_req_per_sec, and burst_limit.
Credits charged: 0

The rate limit of the tier is the only cause of a 429 on an authenticated request. RichAPI never passes a data provider rate limit through as a 429.

How to handle a 429 response correctly

CAUTION: Do not send a rate-limited request again straight away. A tight retry loop keeps the one-second window full and extends the failure.

Read the Retry-After header on the 429 response.
Wait that number of seconds.
Send the same request again.
If the retry also returns 429, double the wait before the next attempt.
Stop after a fixed number of attempts and record the failure.
Lower the number of concurrent requests to the requests-per-second figure of the tier.

Python

import time

import requests

URL = "https://api.richapi.ai/api/v1/enrich_profile"
HEADERS = {"x-api-key": "YOUR_API_KEY", "Content-Type": "application/json"}


def send_with_retry(payload, max_attempts=5):
    wait = 1.0
    for _ in range(max_attempts):
        response = requests.post(URL, headers=HEADERS, json=payload, timeout=60)
        if response.status_code != 429:
            response.raise_for_status()
            return response.json()
        wait = float(response.headers.get("Retry-After") or wait)
        time.sleep(wait)
        wait = wait * 2
    raise RuntimeError("Rate limited after {} attempts".format(max_attempts))


print(send_with_retry({"url": "https://www.linkedin.com/in/satyanadella"}))

Node.js

const URL = "https://api.richapi.ai/api/v1/enrich_profile";
const HEADERS = {
  "x-api-key": "YOUR_API_KEY",
  "Content-Type": "application/json",
};

async function sendWithRetry(payload, maxAttempts = 5) {
  let wait = 1;

  for (let attempt = 0; attempt < maxAttempts; attempt += 1) {
    const response = await fetch(URL, {
      method: "POST",
      headers: HEADERS,
      body: JSON.stringify(payload),
    });

    if (response.status !== 429) {
      if (!response.ok) {
        throw new Error(`Request failed with status ${response.status}`);
      }
      return response.json();
    }

    wait = Number(response.headers.get("Retry-After")) || wait;
    await new Promise((resolve) => setTimeout(resolve, wait * 1000));
    wait = wait * 2;
  }

  throw new Error(`Rate limited after ${maxAttempts} attempts`);
}

const data = await sendWithRetry({
  url: "https://www.linkedin.com/in/satyanadella",
});

console.log(data);

cURL

curl -i -X POST https://api.richapi.ai/api/v1/enrich_profile   
  -H "x-api-key: YOUR_API_KEY"   
  -H "Content-Type: application/json"   
  -d '{"url": "https://www.linkedin.com/in/satyanadella"}'

The -i flag prints the status line and the response headers, so the Retry-After value is visible.

Which requests does the rate limit not count?

RichAPI exempts an asynchronous job status poll from the rate limit of the tier. A status poll never returns 429 for the tier rate, and it costs 0 credits. Poll a job as often as you need.

Does RichAPI enforce a monthly quota?

No. On an authenticated request, RichAPI enforces one limit: the requests-per-second rate of the tier. RichAPI enforces no monthly call quota and no daily call quota. The credit balance is the only volume control.

The Terms page of the dashboard states a monthly quota of 100,000 calls for each API endpoint. RichAPI does not enforce that quota.

What limits apply to the free demo endpoints?

The free demo endpoints under https://api.richapi.ai/api/v1/public/ need no API key. Those endpoints carry a separate limit: a fixed number of calls for each client IP address, for each endpoint, each UTC day. The default is 5 calls per day.

Status over the limit: 429
Body fields: error, api, limit, retry_after_seconds
retry_after_seconds: the seconds until the next UTC midnight
Reset: UTC midnight
Retry-After header: not sent on this response

The demo limit and the tier rate limit are separate limits. An authenticated request never counts against the demo limit.

How long does 100,000 enrichment calls take?

Worked example — 100,000 Profile Enrichment (enrich_profile) calls at 1 credit per call.

Credits: 100,000 calls × 1 credit = 100,000 credits. At the list rate of $0.02 per credit, that is $2,000. The 100,000-credit pack costs $1,500.

Tier	Requests per second	Shortest run time
`base`	1	100,000 seconds, that is 27 hours 47 minutes
`regular`	5	20,000 seconds, that is 5 hours 33 minutes
`power`	10	10,000 seconds, that is 2 hours 47 minutes
`enterprise`	25	4,000 seconds, that is 1 hour 7 minutes

Arithmetic: 100,000 calls ÷ 25 requests per second = 4,000 seconds, that is 1 hour 6 minutes 40 seconds.

One purchase of 100,000 credits pays for the whole run and reaches the enterprise tier in the same billing cycle. The same run on base takes more than a day.

The table counts the rate limit only. Each call also takes provider time. Send several requests at the same time, so that the send rate reaches the tier limit. A client that waits for each response before the next request runs slower than the table shows.

How to ask for a higher rate limit

RichAPI sets a rate above the enterprise tier by agreement.

Write to [email protected].
Name the workspace and its slug.
State the requests per second that you need.
State the endpoints and the daily call volume.
State the date that the volume starts.

Support replies with the rate that RichAPI can set. Past about 50,000 credits a month, Enterprise rate cards price on committed volume and set custom rate limits. Use the Contact Sales button on the Plans & Billing page, or the form at richapi.ai/contact-sales.

Troubleshooting rate limit failures

Symptom	Cause	What to do
Almost every request returns `429` at low volume.	The organization is on the `base` tier, which allows 2 requests in one second.	Buy 5,000 credits or more inside the current billing cycle.
A batch of parallel requests returns `429`.	The client sends more requests inside one second than the burst limit allows.	Lower the concurrency to the requests-per-second figure of the tier.
A retry loop returns `429` on every attempt.	The retries keep the one-second window full.	Wait for the `Retry-After` seconds between attempts, and double the wait after each failure.
A large purchase did not raise the rate.	Stripe has not confirmed the payment yet, or the purchase landed in the previous billing cycle.	Open the Plans & Billing page and read the Transaction History row. Credits count inside one billing cycle.
The rate dropped at the start of the month.	RichAPI recomputes the tier at the start of each billing cycle. Credits bought in the previous cycle do not count for the new cycle.	Buy credits in the current cycle to return to the tier.
The rate dropped after a refund.	A refund lowers the credits counted for the cycle and can lower the tier.	Buy credits in the current cycle to return to the tier.
A request returns `402` and not `429`.	The credit balance is empty. That is a balance failure, not a rate failure.	Ask an organization owner to buy credits on the Plans & Billing page.
You do not know the current rate of the organization.	The rate follows the tier of the organization.	Open the API Keys page and read the Rate Limits card. It shows Requests / Second, Burst Limit, and Plan Tier.

Frequently asked questions

What is the RichAPI rate limit?

The RichAPI rate limit is the number of requests per second that your organization can send, shared by every API key in it. The rate tier sets the number: 1 request per second on base, 5 on regular, 10 on power, and 25 on enterprise.

Does a 429 response cost credits?

No. A 429 response costs 0 credits. RichAPI stops the request before it reaches a data provider, so no credits are reserved and none are charged.

How do I raise my RichAPI rate limit?

Buy more credits inside one billing cycle. 5,000 credits reach the regular tier, 25,000 credits reach the power tier, and 100,000 credits reach the enterprise tier. For a rate above the enterprise tier, write to [email protected].

Does RichAPI have a monthly API call quota?

No. RichAPI enforces no monthly call quota and no daily call quota on an authenticated request. The requests-per-second rate of the tier is the only enforced request limit, and credits control total volume.

How long is the Retry-After wait on a RichAPI 429?

The Retry-After header on a RichAPI 429 is always 1 second. RichAPI counts requests in a one-second window, and that window resets after one second.

Do all API keys in a workspace share one rate limit?

Yes. The limit belongs to the organization and follows the credits it buys in a month. Every API key in the organization counts against the same one-second window. A workspace can hold up to 3 API keys by default.

Does an asynchronous job status poll count against the rate limit?

No. RichAPI exempts a job status poll from the rate limit of the tier. A status poll also costs 0 credits.

Next: Refunds

Understanding Rate Limits and Quotas