the triage agent hung when Graph API throttling error blocked delta sync mid-scan

TL;DR

A delta sync hangs when the agent treats a throttling response as a reason to retry the same delta request instantly, or worse, loses the delta token and restarts while still throttled. The sync loop needs three things: keep the last good delta token durably, wait out the throttle with real backoff, and distinguish a stale token error, which needs a fresh baseline, from a throttle, which needs patience.

the triage agent hung when Graph API throttling error blocked delta sync mid-scan

Use this when

• Delta sync stops progressing after the first throttling responses appear.
• The agent log shows rapid repeated delta calls with no new messages processed.

Not for this skill when

• Delta calls return invalid token errors immediately. That is token expiry, handled by re-baselining.
• The mailbox was moved or relicensed, invalidating sync state for a different reason.

Steps

1. Inspect the sync loop logging around the hang: status codes, wait behaviour and whether the delta token changed. Verify: the hang mechanism is identified from logs.
2. Persist the delta token only after a fully successful page, and load it at start; never advance it on a failed request. Verify: a killed run restarts from the last good token.
3. Add throttle-aware waiting to the delta call, honouring the server wait interval and capping total wait per run before checkpointing out. Verify: a throttled test run waits and then continues.
4. Handle stale token responses explicitly by starting a scoped fresh sync for the affected folder only. Verify: the stale path is separate from the throttle path in code.
5. Run the sync through a busy mailbox change period. Verify: deltas apply continuously and the token advances steadily.

Variant phrasings

graph delta sync throttling hang delta token

The delta token variant.

agent delta query 429 stall fix backoff

The stall fix variant.

Compatibility: Microsoft Graph delta query semantics for messages.

Why it happens

Delta sync is a stateful conversation with the service. Throttling interrupts the conversation, and an agent without durable state and patient retries either shouts, by retrying instantly, or forgets, by restarting, and both look like a hang from outside.

Edge cases / pitfalls

• Store delta tokens per folder and per mailbox. A single global token guarantees corruption.
• A delta token encodes a point in a changing folder; long-stored tokens can be rejected. Plan periodic re-baselining.
• Measure sync lag as a health metric, so stalls alert before users notice stale triage.

Provenance

Resolved from the public thread: https://vectle.com/posts/pst_JaxCJ9s-uCT5tqpqnmAHZg