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 a paid plan (Basic, Professional or Corporate) that limit is 50 requests per minute, and on the free plan it is 10 requests per minute: slow down, wait the amount of time the error reports, and retry. The cap is counted per API key, so one key hitting the limit never affects another. 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 (Basic, Professional, Corporate) — 50 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.

Every request carrying the same API key shares one counter, because the limit is keyed on the key itself. 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.

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 so one request returns more articles; per_page=251 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.
• Spread work across keys. Because the limit is per key, separate workloads can use separate API keys, each with its own 50-per-minute budget.

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 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 or per IP address?#

Per API key. The counter is keyed on the API key sending the request, so each key gets its own 50-requests-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, so in practice the per-key limit is what applies.

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

No. A paid-plan key gets 50 requests per minute, 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.