Your Agent Needs a Rate-Limit Manners Policy, Not Just a Retry Loop

The first time an unattended agent hits a rate limit, it usually looks harmless. A 429 shows up in a log, the retry fires, the job finishes. Nobody notices.

The second time, three cron jobs hit the same provider at the same minute, all get a 429, all retry after exactly five seconds, and all collide again. By the fourth attempt you have burned the quota for the whole hour, and the one job that actually mattered never ran.

That is not a retry problem. It is a manners problem. Your agents are guests on someone else’s API, and they need a written policy for what to do when the host says “not now.”

Why a plain retry loop makes it worse

The default pattern most people copy is: catch the error, sleep a fixed interval, try again, give up after N attempts. It fails in four predictable ways.

Synchronized retries. Fixed delays line up. Ten jobs that failed together retry together, which recreates the exact spike that caused the failure.

Ignoring the server’s hint. Many APIs send a Retry-After header or a reset timestamp. A fixed five-second sleep either wastes time when the real wait is two seconds or hammers the endpoint when the real wait is ninety.

No shared memory. Each job retries as if it were the only caller. Meanwhile the quota belongs to the whole account, so one greedy job starves the rest.

Treating every failure the same. A 429 means “wait.” A 401 means “stop, your credential is broken.” A 500 means “maybe wait, maybe escalate.” A retry loop that handles them identically will politely knock on a locked door all night.

The policy in five rules

You do not need a framework. You need five rules written down where the agent can read them, ideally in the same place you keep your tool contracts.

1. Classify before you retry

Sort responses into three buckets before any sleeping happens:

  • Wait and retry: 429, 503, timeouts, connection resets.
  • Stop and escalate: 401, 403, 404 on a resource that should exist, any schema change in the response.
  • Retry once, then escalate: 500 and 502, which are sometimes transient and sometimes a provider outage.

Only the first bucket gets automatic backoff. The second bucket should never retry, because retrying a bad credential just risks a lockout. If you already run a dead-letter queue, the second bucket is exactly what belongs in it.

2. Obey the server first, your own schedule second

If the response includes Retry-After or a reset time, use it. Add a small safety margin, since clocks drift and the reset moment is not always exact. Only when the server gives no hint should your own backoff curve apply.

Your own curve should be exponential: 2 seconds, 4, 8, 16, 32, capped at something sensible like two minutes for interactive-ish work or fifteen minutes for overnight jobs. A cap matters. Without one, attempt eight sleeps for over four minutes and attempt twelve sleeps for over an hour, which is a failure mode that looks like a hung process.

3. Add jitter, always

Jitter is the cheapest reliability improvement in this whole post. Instead of sleeping exactly 8 seconds, sleep a random value between roughly 4 and 8. “Full jitter,” picking anywhere from zero up to the current ceiling, spreads retries out the most and is a fine default.

Ten jobs that failed together will now retry at ten different moments. The spike flattens on its own, with no coordination required.

4. Give every job a retry budget, and every account a shared one

Per-job budgets stop one workflow from retrying forever: for example, five attempts or ten minutes of total elapsed time, whichever comes first. When the budget runs out, the job stops and records why.

The shared budget is the part people skip. Keep a tiny file or table, one row per provider, that records the last 429 time and a “cooling until” timestamp. Before any job calls that provider, it checks the row. If the provider is cooling, the job does not even try. It reschedules itself or exits with a clear no-op reason.

On a Raspberry Pi running OpenClaw, this can literally be a small JSON file in the workspace. It does not need to be clever. It needs to exist, and every job needs to read it.

5. Make exhaustion loud, not silent

The worst outcome is a job that burns its budget, exits quietly, and leaves a green status somewhere. When a retry budget runs out, the agent should write one plain line: which provider, which job, how many attempts, when the cooling window ends, and what happens next (retry at next scheduled run, or needs human).

That line is what your morning report should surface. A single “provider X throttled us three times overnight, two jobs deferred” is far more useful than a pile of identical error stack traces.

Priority matters when the quota is tight

Quotas are not just limits; they are scarce resources, and scarce resources need priority. If your agent runs a revenue-critical lead responder, a nightly research digest, and a social scheduler off the same API key, those three should not be equals.

Write a short priority order. When the shared cooling flag is set, the lowest-priority jobs skip their run entirely and the high-priority job gets first claim on the next available window. A deferred digest costs you nothing. A deferred lead reply might cost a customer.

This also gives you a natural place to apply a load governor: if cooling events keep happening, the answer is usually not “retry smarter” but “schedule fewer things at the top of the hour.”

Spread the schedule, not just the retries

A surprising amount of rate-limit pain is self-inflicted by cron. Everyone schedules jobs at :00, :15, and :30. Move yours to odd minutes. A job at 7:07 and another at 7:23 will rarely collide, and you never need to debug a collision that cannot happen.

If several jobs call the same provider, stagger them by at least a minute or two, and keep a heavy batch job away from the interactive ones.

A quick test you can run today

Pick the one provider your agents depend on most and answer these questions:

  1. What status codes does your agent retry, and which ones should it not?
  2. Does it read Retry-After, or does it ignore it?
  3. Is there any jitter, or are all delays fixed?
  4. Is there a shared cooling flag, or does each job learn the hard way?
  5. When a job gives up, who finds out, and how?

If you answered “I don’t know” to two or more, you have a retry loop, not a policy. Fixing it is an afternoon of work: a small classification table, a jittered backoff helper, a cooling file, and one line of reporting.

The payoff

Good rate-limit manners do not make your agent faster. They make it boring. Fewer duplicate runs, fewer account warnings, fewer mornings spent working out why three jobs failed at 6:00 and nothing recovered.

An unattended agent earns trust by behaving the same on a bad API day as on a good one. Backoff, jitter, a shared budget, and a loud failure line are how you get there. Write the policy once, put it next to your tool contracts, and let every job inherit it.

More from the build log

Suggested

Want the full MarketMai stack?

Get the core MarketMai guides and operator playbooks in one premium bundle for $49.

View Bundle