How to Handle Rate Limits and API Throttling in OpenClaw

One OpenClaw user reported an agent consuming $47 in API credits overnight because a retry loop hammered a rate-limited provider endpoint without proper backoff. The root cause was not the agent's code. It was a gap between documented and actual rate limit behavior in OpenClaw itself.

Most troubleshooting guides on OpenClaw rate limiting focus exclusively on upstream provider throttling: you send too many requests, the provider returns a 429, and you wait. That covers half the picture. OpenClaw enforces rate limiting at two distinct levels, each with its own configuration surface and failure mode.

Gateway authentication limiter protects your OpenClaw instance from brute-force login attempts. It tracks failed auth per IP address, locks out offenders for 5 minutes by default, and has nothing to do with LLM provider quotas.

Provider-level API throttling manages your relationship with upstream APIs like Anthropic, OpenAI, and Google. When a provider returns a 429 or billing error, OpenClaw can rotate API keys, back off for hours, and fall back to alternative providers.

Confusing the two leads to misdiagnosis. You might tune provider backoff settings when the actual problem is your gateway locking out legitimate agent requests from a shared IP. Or you might ignore the provider cooldown configuration entirely and wonder why your agent keeps retrying a dead API key.

Provider rate limits also vary by tier. Anthropic's Tier 1 (after $5 spend) allows 50 requests per minute. OpenAI's Tier 1 is more generous at 500 RPM. Google Gemini's free tier caps at 15 RPM but costs nothing. Understanding your current provider tier is the starting point for configuring OpenClaw's rate limit handling correctly.

The gateway auth limiter sits in front of OpenClaw's authentication layer and tracks failed login attempts per IP address. Here is the default configuration from the OpenClaw configuration reference:

gateway: {
  auth: {
    rateLimit: {
      maxAttempts: 10,
      windowMs: 60000,
      lockoutMs: 300000,
      exemptLoopback: true,
    }
  }
}

maxAttempts sets the number of failed authentication attempts allowed within the time window. The default of 10 gives reasonable headroom for misconfigured clients without leaving the door open to credential stuffing.

windowMs defines the sliding window in milliseconds. At the default of 60,000ms (one minute), any IP that fails authentication 10 times within 60 seconds triggers the lockout.

lockoutMs controls lockout duration. The default of 300,000ms (5 minutes) means locked-out IPs receive 429 responses until the window expires.

exemptLoopback skips auth rate limiting for requests originating from localhost. Enabled by default, so local development and testing are unaffected.

The limiter tracks each source address independently. Two practical concerns to watch for: reverse proxies that collapse multiple clients into a single IP (which can cause one agent's failures to lock out others), and agents that silently re-authenticate with expired tokens on every request (which burns through the attempt limit even when valid credentials exist). If you run OpenClaw behind a proxy, confirm it forwards real client addresses. If your agents handle token refresh, make sure they rotate tokens before expiry rather than after.

When an upstream provider returns a 429 or billing error, OpenClaw's cooldown system activates. This layer is separate from the gateway auth limiter and operates on a timescale of hours rather than minutes.

auth: {
  cooldowns: {
    billingBackoffHours: 5,
    billingBackoffHoursByProvider: { anthropic: 3, openai: 8 },
    billingMaxHours: 24,
    rateLimitedProfileRotations: 1,
  }
}

billingBackoffHours sets the base backoff when a provider profile fails due to a billing error like an expired credit balance or exceeded spending limit. The default of 5 hours means OpenClaw won't retry that profile for at least 5 hours after the first billing failure. Repeated failures double the wait each time.

billingBackoffHoursByProvider overrides the base backoff per provider. In this example, Anthropic profiles back off for 3 hours while OpenAI profiles wait 8. This is useful when providers have different billing cycle behaviors or when you want faster recovery on your primary provider.

billingMaxHours caps exponential growth. Without this ceiling at 24 hours, repeated billing failures would push backoff durations into multi-day territory, effectively disabling the profile.

rateLimitedProfileRotations controls key rotation on rate limit errors. The default of 1 means: when your Anthropic key gets rate-limited, OpenClaw tries one other Anthropic key (if you have configured multiple profiles) before falling back to a different provider.

Only 429 errors trigger key rotation. A 401 (invalid credentials) or 500 (server error) does not. A 429 means your key is valid but you have exceeded usage limits, so a different key on the same provider might work. A 401 means the key is broken, and rotating to another broken key won't help.

OpenClaw checks for the Retry-After header first when handling rate-limited responses. If that header is absent, it falls back to RateLimit-Reset. If neither header exists, it applies the configured backoff duration. Not all providers send these headers consistently, so the configured defaults act as your safety net.

Running a single provider is a rate limit bottleneck waiting to happen. OpenClaw supports fallback chains that route requests to alternative providers when the primary is throttled.

{
  "models": {
    "primary": "claude-opus-4.6",
    "fallback": [
      "gpt-5.4",
      "gemini-3.1-pro"
    ]
  }
}

When the primary model hits a rate limit and exhausts its rateLimitedProfileRotations, OpenClaw moves to the next provider in the fallback list. Each provider maintains independent rate limit state, so a 429 from Anthropic does not affect your OpenAI or Google quotas.

For task-critical work where output quality matters (legal review, financial analysis, code generation with specific style requirements), set "fallback": false. Waiting for the primary model to recover is better than getting an inconsistent response from an unvetted fallback.

OpenClaw's cron system includes its own retry configuration for scheduled jobs:

cron: {
  retry: {
    maxAttempts: 3,
    backoffMs: [30000, 60000, 300000],
    retryOn: ["rate_limit", "overloaded", "network",
              "timeout", "server_error"],
  }
}

The backoffMs array defines explicit delays between retries: 30 seconds, then 1 minute, then 5 minutes. The retryOn filter selects which error categories trigger retries. This config applies only to one-shot cron jobs. Recurring cron jobs skip retry logic and run again at their next scheduled interval.

Stagger cron schedules to avoid self-inflicted rate limits. Scheduling every nightly job at midnight is a common mistake that concentrates all your API usage into a narrow window. Spread jobs across the hour. Route heartbeat and health-check tasks to Gemini's free tier, which handles 15 RPM at no cost. A multi-step research agent on a nightly cron can burn through an entire Anthropic Tier 1 quota in under an hour, so separating heavy and light tasks across providers is worth the setup effort.

Persist agent outputs across rate limit interruptions

Free 50GB workspace with MCP server access. No credit card, no trial. When your agent hits a rate limit and pauses, its intermediate outputs are already in a shared workspace where your team can review them.

Start 14-Day Trial

OpenClaw's documentation describes exponential backoff for provider 429 errors with escalating intervals: 1 minute, then 5 minutes, then 25 minutes, capping at 1 hour. In practice, this backoff does not work as documented.

GitHub issue #5159 reports measured retry intervals of 1 second, 4 seconds, 1 second, 26 seconds, and 27 seconds, far shorter than the documented minute-scale escalation. The system retries within seconds, hammering the provider repeatedly. This wastes quota on failed requests and risks triggering stricter account-level throttling from the provider.

The issue was closed as "not planned" by OpenClaw maintainers. You cannot depend on OpenClaw's internal retry logic for rate limit recovery. Implement retry logic in your application code instead.

A reliable retry strategy for your agent code:

• Start with a 1-second base delay
• Double the delay on each subsequent retry (exponential backoff)
• Cap maximum delay at 60 seconds
• Add random jitter between 0 and 1 second to prevent multiple agents retrying in sync
• Stop after 5 retries
• Always honor the Retry-After header when the provider includes one, as it overrides your calculated delay

Not every error deserves a retry. Classify them before building your logic:

• 429 (rate limit exceeded): Retryable. Back off and try again.
• 529 (provider overloaded): Retryable, but likely to persist. Consider switching providers immediately rather than waiting.
• 401 (invalid credentials): Not retryable. Fix the API key configuration.
• Quota exhaustion: Not retryable with backoff. Wait for the daily or monthly quota to reset, or switch to a different provider.

For long-running agents, add a circuit breaker: halt execution for 30 minutes after 5 consecutive failures from the same provider. This prevents the scenario from the top of this article, where a broken retry loop drained $47 in API credits overnight because nothing stopped the agent from retrying indefinitely.

Rate limit handling goes beyond retry configuration. A complete strategy prevents unnecessary costs and keeps agents operational through provider outages.

Set provider-side spending limits. Anthropic supports hard monthly caps. OpenAI provides both soft limits (email alerts) and hard limits (request cutoff). Set these at roughly 150% of your expected monthly usage as a financial safety net that catches runaway agents before they do real damage.

Route tasks by model complexity. Simple categorization, summarization, and formatting tasks do not need your most expensive model. Routing these to smaller or cheaper models reduces rate limit pressure on your primary provider and can cut costs by 40 to 60 percent. Reserve high-end models for work where output quality directly affects outcomes.

Watch for hidden rate consumers. Three common culprits drain rate limits without obvious symptoms:

• Cron jobs running simultaneously at the top of each hour
• Health-check heartbeats routed through expensive provider tiers
• Parallel tool calls exceeding concurrency limits on lower-tier accounts (cap at 3 concurrent calls for Anthropic Tier 1)

Monitor proactively. Check provider states with openclaw models status and filter logs for 429 and cooldown events. Track three metrics daily: tokens consumed per workflow, cost per task completion, and wasted tokens from failed requests. These surface problems before they get expensive.

Store intermediate outputs durably. When agents produce partial results between retries, those artifacts need to survive interruptions. Local disk works for single-machine setups. For multi-agent teams, shared cloud storage provides the resilience layer: S3 buckets for raw object storage, Google Drive for quick sharing, or an agent workspace like Fastio (free 50GB, MCP server access, built-in audit trails) for persistent storage that agents and humans share. The goal is ensuring partial work persists so agents resume rather than restart from scratch when rate limits clear.