$cd ../troubleshooting/
API Rate Limit Reached (429) — OpenAI, Anthropic, Gemini
// The '⚠️ API rate limit reached' error means your provider account has hit its requests-per-minute (RPM) or tokens-per-minute (TPM) ceiling. This happens with free/trial tiers and during heavy cron/heartbeat usage.
diagnose.sh
🔍 Is This Your Issue?
?You see '⚠️ API rate limit reached. Please try again later.'
?The error appears across different AI providers (not just one)
?It happens more during peak hours or after extended sessions
openclaw.yaml
✅ Fix 1 — Add Provider Fallback Chain
Add to openclaw.yaml — auto-failover on 429
providers:
- id: primary
type: openai
apiKey: sk-...
- id: fallback1
type: anthropic
apiKey: sk-ant-...
- id: fallback2
type: google
apiKey: AIza...
agents:
defaults:
provider: primary
fallbackProviders:
- fallback1
- fallback2provider_backoff.yaml
✅ Fix 2 — Enable Rate Limit Backoff
Exponential backoff on 429 responses
providers:
- id: primary
type: openai
apiKey: sk-...
rateLimit:
retries: 3
backoffMs: 2000
maxBackoffMs: 30000heartbeat.yaml
✅ Fix 3 — Reduce Heartbeat / Cron Frequency
Reduce heartbeat frequency to lower RPM usage
agents:
defaults:
heartbeat:
interval: "*/30 * * * *" # every 30 min (was 5)
maxTokens: 512 # reduce token usage per runtier_info.txt
✅ Fix 4 — Upgrade Provider Tier
Provider tier comparison
# OpenAI: upgrade to Tier 2+ at platform.openai.com # Anthropic: upgrade at console.anthropic.com # Google: enable billing at console.cloud.google.com # Free tier limits (approx): # OpenAI Tier 1: 500 RPD, 10K TPM # Anthropic Free: 5 RPM, 25K TPM # Gemini Free: 15 RPM, 1M TPD
💡 Pro Tip: Use Multiple Providers
Configure 2-3 providers in a fallback chain. When one hits its rate limit, OpenClaw automatically falls back to the next. This is the most reliable long-term solution.
❓ FAQ
Q1. How do I check my current rate limit tier?
For OpenAI, check platform.openai.com/account/limits — it shows your RPM, TPM, and RPD limits by model. For Anthropic, visit console.anthropic.com/settings/limits. For Google Gemini, check console.cloud.google.com/apis/api/generativelanguage.googleapis.com/quotas. Free tiers typically allow 3-10 RPM. Paying customers start at Tier 1 and can request upgrades after spending thresholds are met.
Q2. Does switching to a local model completely avoid rate limits?
Yes. Running Ollama locally has no rate limits since the model runs entirely on your hardware. This is one of the main advantages of self-hosted AI — you own the inference. The trade-off is that local models require capable hardware (8GB+ VRAM recommended for 7B models) and have higher latency than hosted APIs on fast hardware. For agents that run 24/7, local inference often works out cheaper and more reliable than cloud APIs.
Q3. Will retrying on 429 errors make the problem worse?
Not if you use exponential backoff. OpenClaw has built-in retry logic with increasing delays (2s, 4s, 8s, 16s...) that prevents hammering the API and triggering longer bans. Avoid setting retry intervals below 10 seconds for free-tier API keys. The worst thing to do is implement a tight retry loop — it can trigger IP-level rate limits that persist for hours.
Q4. Why do I hit rate limits even though I'm not sending many messages?
OpenClaw agents can consume tokens in the background without visible user interactions. Common causes: (1) Heartbeat agents running every 5 minutes with long system prompts — each heartbeat consumes TPM even if no user is actively chatting. (2) Tool calls that trigger multiple model invocations per user message. (3) Streaming responses that re-open connections frequently. Check your provider dashboard's usage graph for the time pattern — spikes every N minutes suggest a heartbeat or scheduled task is the culprit.
Q5. Can I use multiple API keys to increase my effective rate limit?
Technically yes, but this may violate your provider's terms of service. OpenAI's terms prohibit using multiple accounts to circumvent rate limits. The supported approach is to use multiple different providers in a fallback chain — one OpenAI key plus one Anthropic key plus one Gemini key gives you three independent rate limit buckets. Each provider's free or paid tier is additive from a capacity standpoint.
Q6. How do I know which agent or skill is hitting the rate limit?
Enable debug logging in OpenClaw (log_level: debug) and watch for lines tagged with the provider name. Each API call will log the agent ID, token count, and provider used. You can also check your provider dashboard's usage breakdown — OpenAI shows per-key usage if you use separate API keys per agent. Alternatively, set per-agent maxTokens limits in config.yaml to cap how much each agent can consume per run.