Detect and Recover When Your AI Agent Hits an API Rate Limit
By MobileVibe Team · August 28, 2026 · 12 min read
Detect and Recover When Your AI Agent Hits an API Rate Limit
Quick answer
When your AI agent hits an API rate limit, it stops mid-task and waits—often silently—until the quota resets. You can detect this by watching for “needs approval” states, quota-exceeded messages, or stalled progress notifications, then recover by approving a retry, pausing the conversation, or switching to a different agent or folder until the limit clears.
Key takeaways
- Rate limits are time-based quotas enforced by AI providers (tokens-per-minute, requests-per-day) that pause your agent when exceeded.
- Detection signals include “needs approval,” explicit quota messages, or conversations that stop progressing without error.
- Immediate recovery means approving a retry once the window resets, pausing the agent, or switching to a parallel lane.
- Multi-agent workflows require staggered starts and per-folder quota awareness to avoid gridlock.
- Provider-specific handling varies: Claude IDE and CLI share native rate-limit state; Codex CLI and extension track separately; Cursor and Windsurf surface limits through their host apps.
- Mobile monitoring with push or email notifications lets you unblock an agent stuck on rate limit from anywhere.
Why Rate Limits Stop Your Agent Mid-Task
AI coding agents—Claude, Codex, Cursor, Windsurf—call provider APIs to generate code, analyze diffs, and plan next steps. Every provider enforces rate limits: caps on how many tokens or requests you can consume in a rolling window (per minute, per hour, per day). When your agent exhausts its quota, the API returns a 429 error or quota-exceeded response, and the agent pauses. It won’t resume until the rate-limit window resets.
This matters because agents don’t fail gracefully. A stalled agent looks like a conversation that needs input or approval, but the real blocker is time, not a missing answer. If you’re away from your desk—commuting, in a meeting, or asleep—the agent sits idle, burning hours of potential progress. The task you started in the morning may still be waiting when you check your phone at lunch, not because it hit a logic problem, but because it hit a quota wall at 9:03 AM and the per-hour limit didn’t reset until 10:03 AM.
Rate limits are per-account and per-tier. Free tiers have tight windows (e.g., 40,000 tokens per minute for Claude Sonnet 3.5 on the free plan); paid tiers raise the ceiling but never eliminate it. If you run multiple agents in parallel—say, three worktrees each with a Codex session—they all draw from the same account quota, so one agent’s burst can starve the others.
Spotting Rate-Limit Signals Before Your Agent Stalls
The clearest signal is an explicit quota message in the conversation: “Rate limit exceeded. Try again in 42 seconds.” Claude IDE, Codex CLI, and Cursor will surface this in the chat or terminal output. But many agents don’t announce the limit—they just stop and wait for you to approve the next step.
Look for these patterns:
- “Needs approval” or “waiting for input” states that appear immediately after a burst of API calls (multiple file edits, a large refactor, or a complex plan).
- Stalled progress where the agent generated half a file, then went silent. Check the timestamp: if it’s been 15 minutes with no new output, it’s likely waiting on a quota reset, not thinking.
- Provider dashboard warnings (e.g., Anthropic Console, OpenAI usage page) showing you’re near or over your tier’s limit.
- Push or email notifications from MobileVibe flagging a conversation that “needs approval” or “hit a quota.” If you get this alert within seconds of the agent starting, it’s almost always a rate limit.
If you’re running multiple agents in parallel, watch for cascading stalls: one agent hits the limit, then the next one does five minutes later, then the third. That’s a sign your account quota can’t support the combined load.
Immediate Recovery: Approve, Pause, or Retry
Once you’ve confirmed an agent is stuck on a rate limit, you have three recovery paths:
1. Approve and retry
If the rate-limit window has reset (check the provider’s error message for the exact wait time), approve the agent’s next step. In Claude IDE or Codex CLI, this means clicking “Continue” or typing y in the terminal. In MobileVibe, open the conversation on your phone, review the last message, and tap “Approve” or reply with your next instruction. The agent will resume from where it paused.
When to use this: The limit was short (under five minutes), the task is time-sensitive, and you’re confident the agent won’t immediately hit the limit again.
2. Pause the conversation
If the rate-limit window is long (per-day limits can block you for hours), pause the agent and come back later. In MobileVibe, you can mark the conversation as “paused” or simply leave it; the agent won’t consume quota while idle. Use the wait time to review diffs, plan the next phase, or switch to a different project.
When to use this: The limit won’t reset for 30+ minutes, or you want to preserve quota for a higher-priority task.
3. Switch agents or surfaces
If you have access to multiple agents (e.g., both Claude and Codex) or multiple surfaces (Claude IDE and Claude CLI), move the task to a lane that hasn’t hit its limit yet. Copy the conversation context (the last few messages or the task description) and start a new conversation in the alternate surface. This works best when the agents share a common model (e.g., both use GPT-4 or Claude Sonnet) and the task doesn’t depend on deep history.
When to use this: You need progress now, and you have unused quota in another account or agent.
Prevent Rate-Limit Gridlock Across Multiple Agents
Running several agents in parallel is a core MobileVibe workflow—three worktrees, three folders, three conversations. But if all three agents draw from the same account quota, they can deadlock: each one starts, hits the limit, waits, and by the time the first one resumes, the second one has already consumed the reset quota.
Stagger your starts. Launch the first agent, let it run for a few minutes, then start the second. This spreads the quota load across time and reduces the chance of simultaneous stalls.
Assign priority lanes. Decide which folder or conversation is most time-sensitive, and give it first claim on quota. Pause or throttle the lower-priority agents (e.g., run them only during off-peak hours or after the primary task completes).
Use separate accounts or tiers. If you’re hitting limits daily, consider upgrading to a paid tier (higher per-minute caps) or splitting work across multiple provider accounts. Claude Pro, for example, raises the Sonnet 3.5 limit to 80,000 tokens per minute—double the free tier. Codex and Cursor have similar tier structures.
Monitor quota in real time. Check your provider dashboard (Anthropic Console, OpenAI usage page) before starting a heavy task. If you’re already at 80% of your daily limit, defer the task or use a different agent.
Quota Monitoring and Notification Setup
You can’t fix an agent stuck on rate limit if you don’t know it’s stuck. Set up push or email notifications so you’re alerted the moment a conversation needs attention.
In MobileVibe, enable notifications for “needs approval” and “quota exceeded” events. When an agent hits a rate limit, you’ll get a push alert on your phone within seconds. Open the conversation, review the last message, and decide whether to approve, pause, or switch lanes. If you’re in a meeting or away from your phone, the email loop works too: reply to the notification email with your next instruction, and MobileVibe will relay it to the agent.
In Claude IDE, the app will show a banner or toast when a rate limit is hit. If you’re using the CLI (claude), the terminal will print the error and wait for you to press Enter. In Codex CLI (codex), you’ll see a similar message. Cursor and Windsurf surface rate-limit errors through their host-app UI, often as a modal or status-bar warning.
Provider dashboards offer usage graphs and alerts. Anthropic Console shows your current tier, tokens consumed, and time until the next reset. OpenAI’s usage page breaks down requests by model and time window. Check these before starting a large task to confirm you have headroom.
Rate-Limit Handling by Provider (Claude, Codex, Cursor, Windsurf)
Claude (IDE and CLI)
Claude IDE and CLI share the native Claude store, so rate-limit state is consistent across surfaces. If you hit a limit in the IDE, the CLI will see the same quota. This makes cross-surface resume straightforward: pause in the IDE, wait for the reset, then continue in the CLI (or vice versa). The free tier caps Sonnet 3.5 at 40,000 tokens per minute; Claude Pro doubles that to 80,000. Per-day limits are higher but still enforced.
Recovery: Approve the next step once the window resets. If you’re using MobileVibe, the conversation will show “needs approval” and you can tap to continue.
Codex (CLI and IDE extension)
Codex has a separate IDE extension and MobileVibe’s native headless codex-cli. Rate limits are per-account (OpenAI), but the two surfaces don’t share local history, so moving a conversation between them may require copying context. The free tier (if available) has tight per-minute caps; paid tiers (e.g., GPT-4 Turbo) offer higher limits.
Recovery: If the CLI hits a limit, you can switch to the IDE extension (or vice versa) and start a new conversation with the same task description. The new surface will have the same account quota, but the local session state is independent.
Cursor
Cursor is a separate host app, not a VS Code alias. It uses OpenAI or Anthropic models under the hood, so rate limits depend on your provider tier. Cursor surfaces quota errors through its UI (status bar, chat panel). Full history enumeration or Claude-like surface switching should not be assumed—Cursor’s conversation state is tied to the app.
Recovery: Approve the retry in Cursor’s UI once the limit clears. If you’re using MobileVibe to monitor Cursor sessions (where supported), you’ll see the “needs approval” state on your phone.
Windsurf
Windsurf is another separate host app with its own conversation model. Rate-limit handling is similar to Cursor: the app will show an error, and you approve the retry once the window resets. MobileVibe’s live driving or host-app support (where available) lets you monitor and approve from mobile, but full history parity with Claude or Codex should not be assumed.
Recovery: Use the host app’s UI to approve the next step, or (if supported) approve via MobileVibe’s mobile interface.
Resuming Conversations After Limits Clear
Once the rate-limit window resets, resuming is usually as simple as approving the next step. But there are nuances:
Check the reset time. Most rate limits are rolling windows (e.g., “40,000 tokens in the last 60 seconds”). If you hit the limit at 9:03:00 AM, it clears at 9:04:00 AM—not at the top of the hour. Provider error messages often include the exact wait time; use that to decide whether to pause or switch tasks.
Review the last message. Before approving, skim the agent’s last output. If it was mid-edit or mid-plan, make sure the context is still valid. If the task has changed (e.g., you pushed a new commit, or a teammate merged a conflicting PR), give the agent updated instructions instead of blindly continuing.
Use auto-approve where supported. If you trust the agent and the task is low-risk (e.g., running tests, formatting code), enable auto-approve in MobileVibe. The agent will retry automatically when the limit clears, without waiting for you to tap “Approve.” This is especially useful for overnight or weekend tasks.
Switch surfaces if needed. If the original surface (e.g., Claude IDE) is still rate-limited but you have quota in another surface (e.g., Claude CLI), start a new conversation there. Copy the last few messages or the task description, and the agent will pick up where the first one left off. This works best when both surfaces share the same model and provider.
Monitor for cascading limits. If you’re running multiple agents, resuming one may trigger a limit in another. Stagger your resumes the same way you stagger your starts: let the first agent run for a few minutes before resuming the second.
FAQ
How do I know my agent is stuck on a rate limit vs. another error?
Look for explicit quota messages (“Rate limit exceeded,” “429 error”) in the conversation or terminal output. If there’s no error message but the agent stopped mid-task and shows “needs approval,” check the timestamp: if it’s been 5–15 minutes with no progress, it’s likely a rate limit. Provider dashboards (Anthropic Console, OpenAI usage page) will confirm if you’re over your tier’s cap. Other errors (syntax issues, missing files, auth failures) usually produce specific error text.
Can I approve an agent to retry automatically when the rate limit clears?
Yes, if the agent or surface supports auto-approve. In MobileVibe, enable auto-approve for the conversation; the agent will retry once the rate-limit window resets, without waiting for manual approval. This works best for low-risk tasks (tests, formatting, incremental edits). For high-risk tasks (production deploys, large refactors), manual approval is safer.
How long does a typical API rate limit last?
Most rate limits are rolling windows: 60 seconds for per-minute limits, 24 hours for per-day limits. If you hit a per-minute limit at 9:03:00 AM, it clears at 9:04:00 AM. Per-day limits reset at midnight UTC (or your account’s timezone). Provider error messages often include the exact wait time (e.g., “Try again in 42 seconds”). Check your provider’s docs for tier-specific windows.
What’s the difference between per-minute and per-day rate limits?
Per-minute limits cap how fast you can consume tokens or requests in a short burst (e.g., 40,000 tokens in 60 seconds). These reset quickly but are easy to hit during intensive tasks (large file edits, complex plans). Per-day limits cap total usage over 24 hours (e.g., 1 million tokens per day). These are harder to hit but block you for hours once exceeded. Most providers enforce both; you can hit one without hitting the other.
Can I run multiple agents in parallel without triggering rate limits?
Yes, but you need to stagger starts and monitor total quota. If all agents draw from the same account, their combined usage counts toward your tier’s limit. Start the first agent, let it run for a few minutes, then start the second. Assign priority lanes so the most time-sensitive task gets first claim on quota. If you’re hitting limits daily, upgrade to a paid tier or split work across multiple accounts.
Does MobileVibe notify me when an agent hits a rate limit?
Yes. Enable push or email notifications for “needs approval” and “quota exceeded” events. When an agent hits a rate limit, you’ll get an alert on your phone within seconds. Open the conversation in MobileVibe, review the last message, and approve the retry, pause the agent, or switch to a different lane. The email loop works too: reply to the notification email with your next instruction, and MobileVibe will relay it to the agent.
When your agent hits a rate limit mid-task, every minute it sits idle is a minute you’re not shipping. MobileVibe lets you detect the stall, approve the retry, or switch lanes—all from your phone, so you’re never waiting on a quota reset you didn’t know about. Try it free at mobilevibe.com and keep your agents moving, even when the API says “wait.”
