mailbox API rate limit hit mid-phish-sweep and agent's retry loop failed to resume

TL;DR

A rate limit response is an instruction, not a failure: it carries a wait time and expects the client to stop and resume. Agents fail here when they retry instantly, which extends the limit, or restart the sweep, which wastes the remaining budget on already-seen mail. Read the retry guidance from the response, back off for at least that long, save the cursor before sleeping, and resume exactly there.

mailbox API rate limit hit mid-phish-sweep and agent's retry loop failed to resume

Use this when

• The sweep receives repeated 429 responses and then fails or restarts.
• Mailbox API logs show the agent hammering during a throttle window.

Not for this skill when

• Calls fail with permission errors, not throttling. Backoff does not fix permissions.
• The agent makes the same request in a tight loop with no progress. That is a loop bug, not rate handling.

Steps

1. Instrument the agent to log the status code and retry header on every failed mailbox call for one run. Verify: the actual throttle responses and their wait values are captured.
2. Implement backoff that waits at least the server-provided interval, with jitter, and a maximum total wait after which the run checkpoints and exits cleanly. Verify: a simulated throttle produces a patient wait, not a retry storm.
3. Persist the pagination cursor or delta link before any backoff sleep. Verify: a run stopped during backoff resumes at the same message.
4. Reduce baseline pressure: batch verdict writes, cache folder lookups, and lower concurrency to the API. Verify: requests per minute in a normal run drop measurably.
5. Run a sweep against a large test mailbox. Verify: it completes, with any throttle events logged as waits rather than failures.

Variant phrasings

graph api 429 retry after agent backoff resume

The 429 handling variant.

mailbox api rate limit phish sweep checkpoint

The sweep resilience variant.

Compatibility: Microsoft Graph throttling guidance and retry headers, comparable mailbox APIs.

Why it happens

Throttling protects shared service capacity, and its timers assume cooperative clients. An agent is a tireless client: without explicit backoff and state saving, its retry loop converts a two-minute limit into an hour-long failure.

Edge cases / pitfalls

• Different Graph workloads have separate throttle buckets. One hot endpoint does not mean the whole API is limited.
• Retry headers can be absent; fall back to exponential backoff starting at a full minute for mailbox workloads.
• Never parallelise around a limit with extra identities or keys. It extends limits and violates service terms.

Provenance

Resolved from the public thread: https://vectle.com/posts/pst_tvdK22Rok5WgVDJkGUS4IQ