Rate Limits & QPS Tiers — ApiTwitter

ApiTwitter rate limits explained: 0.2 to 30 QPS based on balance. Auto-upgrading tiers, rate limit headers (X-RateLimit), Retry-After, and how to avoid HTTP 429 errors on the Twitter/X API.

Understanding QPS

QPS (Queries Per Second) determines the maximum number of API requests you can make per second. Your limit scales automatically based on your account balance.

QPS Tiers

Tier	Balance	QPS Limit	Requests/Sec
Free	$0	0.2	1 every 5 seconds
Starter	> $0	3	3 per second
Basic	> $1	5	5 per second
Pro	> $5	10	10 per second
Business	> $50	30	30 per second

Your QPS tier upgrades instantly when you add credits. No plan changes needed.

Rate Limit Headers

Every API response includes these headers:

Header	Description	Example
X-RateLimit-Limit	Your current QPS limit	10
X-RateLimit-Remaining	Remaining requests in window	7
X-RateLimit-Tier	Your current tier name	Pro
Retry-After	Seconds to wait (only on 429)	1.5

Exceeding the Limit

When you exceed your QPS limit, you receive a 429 Too Many Requests response:

{
  "status": "error",
  "msg": "Rate limit exceeded. Your tier (Free) allows 0.2 QPS. Top up your balance to unlock higher request rates.",
  "tier": "Free",
  "qps_limit": 0.2,
  "retry_after": 1.5
}

If you’re hitting rate limits, add credits to instantly upgrade your tier, or add a delay between requests.

Free User Limitations

Free users (balance = $0) can make one request every 5 seconds (0.2 QPS). This is intentionally restrictive to encourage recharging.

To unlock higher rates, top up any amount starting from $10.

Rate Limit FAQ

How do I increase my QPS limit?

Simply add credits to your account. Your QPS tier upgrades instantly based on your balance — no plan changes or requests needed. A balance above $50 gives you the maximum 30 QPS.

Does each endpoint have its own rate limit?

No. The QPS limit is global across all endpoints. If your limit is 10 QPS, that means 10 total requests per second to any combination of endpoints.

What should I do when I get a 429 error?

Wait for the number of seconds indicated in the Retry-After header, then retry. To permanently avoid 429 errors, add credits to increase your QPS tier or add delays between requests.