How to fix rate-limit (429) errors#

A 429 Too Many Requests response means you sent more requests than your per-minute limit allows. On Starter, Basic and Professional that limit is 50 requests per minute, on Corporate 200 requests per minute, and on the free plan 10 requests per minute: slow down, wait the amount of time the error reports, and retry. The cap is counted per account, so every live key you own shares it — one busy key does eat into the budget of the others. A blocked request returns this body:

{
  "status": "not_ok",
  "request_id": "…",
  "errors": [
    {
      "status": 429,
      "code": "ER0203",
      "message": "Rate limit exceeded. You can make 50 requests per minute. Try again in 1 minute.",
      "links": { "about": "https://docs.apitube.io/platform/news-api/http-response-codes" },
      "timestamp": "…"
    }
  ]
}

What are the request limits?#

APITube applies a one-minute window, and the ceiling depends on your plan and key type:

• Paid plans (Starter, Basic, Professional) — 50 requests per minute. Corporate — 200 requests per minute.
• Free plan — 10 requests per minute.
• Test keys — 15 requests per minute. Test data does not draw down your quota, so the rate limit is the only backstop and is set lower.
• Fact-check (/v1/fact-check) — 10 requests per minute, on its own counter separate from the plan pool, because each call runs a language model.

The counter is keyed on the account, not on the individual key: every live key you own draws from the same per-minute budget, so issuing more keys does not raise your ceiling. Test keys (api_test_) keep a separate counter with their own 15/min limit, and your IP address is used only as a fallback when no key is present.

What does a 429 response look like?#

Exceeding the limit returns HTTP 429 with error code ER0203. The JSON body follows the standard APITube error shape shown above: a status of not_ok, your request_id, and an errors array. The message states both your ceiling and how long to wait — for example, “You can make 50 requests per minute. Try again in 1 minute.” Read that wait time and hold further calls until it passes instead of retrying immediately.

Why am I temporarily banned (ER0204)?#

If you keep sending requests after hitting the limit — 30 over-limit responses — the key is temporarily banned. A ban returns HTTP 429 with code ER0204 and the message “You have been temporarily banned for exceeding rate limits. Try again in …”. The ban is temporary and clears after the stated interval. The fix is the same as for ER0203, but more urgent: stop sending requests and back off, rather than retrying in a tight loop that keeps the ban alive.

What is ER0184, and how is it different?#

ER0184 is also HTTP 429, but it is a concurrency limit rather than a rate limit: it caps how many queries your account may run at the same moment — 1 on Free, 2 on Starter and Basic, 3 on Professional, 4 on Corporate. Requests above the cap wait briefly in a queue, so you only see ER0184 when that queue is full or a queued request timed out. The response includes a Retry-After header. The fix is different too: reduce how many calls you fire in parallel (a smaller worker pool), not how often you call. Streaming endpoints are exempt — /v1/news/stream and /v1/news/ws never return ER0184.

How do I avoid hitting the limit?#

Treat the 50-per-minute cap as a budget and shape traffic to stay under it:

• Back off on 429. When you get ER0203, pause for the time the message reports — or use exponential backoff — before retrying. Never retry in a tight loop, or you risk the ER0204 ban.
• Fetch more per call. Raise per_page up to its maximum of 250 — 50 on Starter, 10 on Free — so one request returns more articles; going over the ceiling is rejected with ER0171. Fewer, larger pages mean fewer requests. See How to paginate through results.
• Count before you download. Use /v1/news/count to learn how many articles match a filter without pulling them — a cheap way to size a job before paging through it. See How to count matching articles.
• Do not expect extra keys to help. The budget is shared across every live key on the account, so splitting a workload over several keys gives no extra throughput — pace the calls instead. Separate keys are still worth having for attribution and for scoping permissions.

A rejected request is cheap in one way: the rate-limit check runs before the request is processed, so a 429 does not consume a request from your quota. Only processed, delivered responses are billed.

Common Questions#

• Is the rate limit per API key, per account or per IP address?
• Do test keys and fact-check share the 50-per-minute limit?
• How long does an ER0204 ban last?
• Does a 429 error use up one of my requests?

Is the rate limit per API key, per account or per IP address?#

Per account. The counter is keyed on the account behind the request, so all of your live keys share one 50-requests-per-minute budget (200 on Corporate, 10 on Free) — issuing more keys does not raise it. Test keys (api_test_) are counted separately, with their own 15-per-minute budget. The IP address is used only as a fallback when a request arrives without a key, and unauthenticated requests are rejected at authentication first.

Do test keys and fact-check share the 50-per-minute limit?#

No. A Starter, Basic or Professional key gets 50 requests per minute, Corporate gets 200, the free plan gets 10, a test key gets 15 per minute, and the /v1/fact-check endpoint has its own 10-per-minute limit counted separately from your general request pool. Hitting the fact-check limit does not block your other News API calls, and the reverse is true as well.

How long does an ER0204 ban last?#

The ban is temporary. The ER0204 message includes a “Try again in …” interval — wait until it elapses, then resume at a slower pace. Continuing to send requests during the ban only keeps it active, so stop and back off.

Does a 429 error use up one of my requests?#

No. Rate limiting happens before the request is processed and billed, so a 429 (either ER0203 or ER0204) does not deduct from your request quota. Only requests that are actually processed and returned count against your plan.