Skip to main content
Two separate things constrain API use, and confusing them wastes time:
  • Rate limits cap how fast you can make requests. Per credential, per minute.
  • Usage limits cap how much data you can collect. Set by your plan, counted daily or monthly.
A rate limit answers RATE_LIMITED (429) and waiting fixes it. A usage limit answers USAGE_LIMIT_EXCEEDED (402) and waiting a minute does nothing.

​
The limits

Counted in a fixed 60-second window, keyed on the credential — rl:key:<keyId> for a key, rl:user:<userId> for a person. API keys get the higher allowance deliberately: an agent or script working through a task legitimately makes far more calls in a minute than someone clicking around a dashboard.
These are lower than they look if you’re paginating in a loop. 120 requests a minute is two per second — a naive export that pages through 5,000 keywords at the default page size will hit it.

​
Counted per credential, not per IP

An IP is shared by everyone behind one office NAT and changes for a single user on mobile, so it bounds the wrong set in both directions. The credential is the thing whose usage is worth limiting. A practical consequence: several API keys in one organization each get their own budget. That’s another reason to give each consumer its own key.

​
Response headers

Every rate-limited response carries: A 429 additionally carries Retry-After, in seconds. Wait that long — retrying sooner just consumes another slot against a window that hasn’t reset, which is what turns a rate limit into a thundering herd.
Read X-RateLimit-Remaining on ordinary responses and slow down before you hit zero, rather than reacting to the 429.

​
It fails open

If the counter’s backing store is unreachable, requests are allowed through rather than rejected. An outage in the rate limiter must not become an outage of the product. Don’t rely on that — it’s a safety property, not a mode you can plan around.

​
Staying under

  • Raise your page size. per_page goes up to 500. Paging 5,000 rows at 25 costs 200 requests; at 500 it costs 10. See Pagination.
  • Poll jobs at a sensible interval. An audit takes minutes to an hour — polling every second is thousands of requests for one answer. See Jobs and polling.
  • Use the CSV export endpoints for bulk reads.
  • Don’t re-fetch stored data in a loop. Most endpoints return data that only changes when a scheduled job runs.