Fixing "API rate limit reached, please try again" in OpenClaw

Your agent was mid-task, maybe halfway through a long research run, and suddenly every reply fails with the same line: API rate limit reached, please try again. Waiting a few seconds does not help, retrying the message does not help, and the error does not say which limit you hit or when it resets. Here is what is actually happening and how to make it stop, both right now and permanently.

API rate limit reached, please try again

This message means the upstream model provider, not OpenClaw, rejected the request with an HTTP 429. Your API key exceeded one of the provider's throughput caps, usually requests per minute or tokens per minute. OpenClaw is relaying the provider's refusal. Two things it is not: it is not an OpenClaw bug, and it is not a billing problem. Out-of-credit errors look different ("insufficient credits", "credit balance too low") and OpenClaw handles them on a separate path.

Agents hit rate limits faster than humans do because a single agent turn can fire several model calls in quick succession: tool calls, memory lookups, sub-agents, heartbeats, and cron jobs all count against the same key.

What the limit means on each provider

Anthropic

Anthropic enforces requests per minute plus separate input and output tokens per minute, per model. Limits scale with your usage tier, which rises as your account spends more over time. Every 429 includes a retry-after header saying exactly how long to wait; for token-bucket limits, 60 seconds is usually enough for the bucket to refill.

OpenAI

OpenAI applies per-model RPM and TPM caps based on your usage tier (tier 1 through 5, determined by cumulative spend and account age). New keys on low tiers throttle quickly under agent workloads. Note the difference between a 429 rate limit and a 429 with "insufficient_quota": the second one is billing, and no amount of waiting fixes it.

Groq

Groq's free tier is generous on speed but strict on volume, with low per-model requests-per-minute and daily token ceilings. Agents burn through free-tier daily caps fast. If Groq is your primary provider, upgrading to the paid developer tier or keeping a fallback model configured is close to mandatory.

What OpenClaw already does for you

OpenClaw classifies the failure as a rate limit and reacts on its own. Knowing the built-in behavior saves you from fighting it:

• Cooldowns per auth profile: the failing credential is put in cooldown for 30 seconds on the first failure, 1 minute on the second, and 5 minutes from the third failure on. Counters reset after a clean 24-hour window.
• One rotation, then fallback: by default OpenClaw retries once with another auth profile on the same provider (if you have one), then moves to the next model in your configured fallbacks instead of waiting.
• Capped waits: if a provider asks for a very long retry-after, OpenClaw caps SDK-internal waits at 60 seconds so it can fail over instead of hanging.
• Automatic recovery: after falling back, OpenClaw re-probes your primary model every 5 minutes and switches back once it recovers, posting a visible "Model Fallback" notice on each state change.

Fix it step by step

1. Identify the throttled provider and model. Run /status in your chat surface. It shows the selected model and, when fallback is active, which model is actually serving and why.
2. Wait out the window. For a first offense this is 30 to 60 seconds. If the error repeated several times, the cooldown may be 5 minutes; OpenClaw re-probes on its own, so resist hammering retry.
3. Configure model fallbacks. This is the permanent fix. Put your fallbacks on a different provider so one vendor's throttle never idles your agent:

   {
     agents: {
       defaults: {
         model: {
           primary: "anthropic/claude-sonnet-4-5",
           fallbacks: ["openai/gpt-5.2", "groq/llama-3.3-70b-versatile"]
         }
       }
     }
   }

4. Add a second auth profile for your main provider. With two credentials, OpenClaw rotates to the healthy one before falling back to another model, keeping replies on your preferred model.
5. Reduce the burn rate. Route routine work to a cheaper, higher-limit model and reserve the flagship model for hard tasks. Long sessions also inflate token usage per turn; starting a fresh session with /new shrinks each request. Check cron jobs and heartbeats that silently spend your quota in the background.
6. Raise the ceiling. If you are hitting limits daily, request a tier upgrade from the provider. Anthropic and OpenAI both raise limits with spend history, and Groq's paid tier removes most free-tier caps.

One caveat about pinned models

If you selected a model explicitly with /model, OpenClaw treats that as an exact user choice and will not silently answer from a fallback. It reports the rate limit instead. That is intentional: an explicit selection means you want that model or an error, not a surprise substitute. Switch back to your configured default (or a fresh session) to re-enable fallback behavior.

Why does the error keep appearing after the provider limit reset?

OpenClaw applies its own short cooldown to the failing credential, up to 5 minutes after repeated failures. This prevents hammering a throttled key, which some providers penalize. The cooldown clears automatically, and OpenClaw re-probes the primary model about every 5 minutes.

Will OpenClaw switch to another provider automatically?

Only if you configured fallbacks under agents.defaults.model.fallbacks. Without them, OpenClaw retries the same provider with cooldown and rotation rules and reports the failure if the provider stays throttled. With them, it walks the chain in order and returns to your primary once it recovers.

Is "rate limit reached" the same as running out of credits?

No. Rate limits are speed caps that recover on their own within seconds or minutes. Credit and billing errors mean the account cannot pay for the request, and OpenClaw disables that credential for hours instead of a short cooldown. If topping up your balance fixes it, it was billing, not a rate limit.