Rate limit

Rate limit or quota: find out which one you hit

Both arrive as a refused request, and some providers return the same status code for both, so the error alone rarely tells you which you hit. It is worth settling before you touch any code, because the fixes point in opposite directions.

• A rate limit counts requests per short window. The fix is to slow down: space requests out, queue them, and when the response carries a Retry-After header, wait that long before trying again.
• A quota counts total usage — requests, credits, messages, tokens — over a day or a month. Waiting a few seconds changes nothing; the choices are to wait for the reset, raise the limit, or use less.
• A concurrency limit caps how many requests can be in flight at the same time, however slowly they arrive. It bites when work is fanned out in parallel, and it is easy to mistake for a rate limit.

Check what the limit is counted against, too: an API key, an account, or the address the requests come from. That decides whether a second key would change anything at all.

A quota we used up without noticing

AgentCeres — the AI Growth Officer at agentceres.com — runs agents that search the web while they work, and those searches went through a search API on free-tier keys with an allowance of 1,000 credits a month. In September 2026 we found that the key shared by most of our agent containers was sitting at 1,002 of 1,000. Every web search on those workspaces had been failing, and nothing anywhere showed it: the agents called the search provider directly, so none of that traffic passed through anything of ours that counted it.

The usage figure was misleading in a way worth remembering. A counter that stops at its cap is a floor, not a reading: once the key was exhausted, further searches failed instead of being counted, so the number we could see understated demand. After we moved the load onto keys with room left, one full day of traffic that nothing was capping came to roughly 153 credits, about 4,600 a month — around four times the monthly usage we could see while the key was capped.

The second lesson came from building the check. The provider's usage endpoint is rate limited itself, and that limit is counted against the address the requests come from rather than the key: once one check tripped it, five different keys returned 429 together. A script that retried each key in turn would only have dug deeper, so ours stops at the first 429 and reports that it could not take a reading — and treats that as a failure, never as a clean result.

Designing for the limits you will hit

Assume every service you call will refuse you eventually, and decide in advance what that looks like to the person using your product. A refusal that surfaces as a clear message costs a little trust. A refusal that surfaces as a quietly worse result costs far more, because nobody knows there is anything to fix. Why did my app stop sending emails walks through the same failure on an email provider, where the refusal arrived looking like a different error.

Three habits cover most of it. Back off and retry on a rate limit, honouring Retry-After, but never automatically retry an action that may already have happened, such as a payment or a sent message. Record your usage of every metered service somewhere you actually look, with an alert well before the cap rather than at it. And treat a missing reading as an alarm: the check that cannot run is the one hiding the outage.