CRM API rate limit hit mid-account-sync: agent failed to back off and retry

TL;DR

Rate limits are a contract: the API tells you the limit and often the reset time, and the agent's job is to slow down, not to die or to hammer. Read the 429 response headers, back off with jitter, persist progress per account, and resume where the sync stopped instead of restarting into the same wall.

CRM API rate limit hit mid-account-sync: agent failed to back off and retry

Use this when

• Sync logs show 429 responses followed by run failure
• The agent retries immediately or not at all
• Progress before the failure is lost and the sync restarts

Not for this skill when

• The account's API quota is genuinely exhausted by other integrations
• The errors are 403 permissions, not 429 limits

Steps

1. Inspect the failing calls: endpoint, limit headers returned, and the agent's retry behaviour in code. Verify: the limit values and the missing backoff are documented
2. Implement backoff that reads the reset guidance, adds jitter, and caps total wait per account. Verify: a simulated 429 now slows the sync instead of killing it
3. Persist per-account sync state so a stopped run resumes at the first unsynced account. Verify: resume behaviour is proven by killing a test run mid-sync
4. Reduce call volume: batch reads, cache reference data, and sync changed accounts only. Verify: calls per sync drop measurably against the old baseline
5. Add a rate-limit dashboard or log alert when 429s exceed a small daily count. Verify: limit pressure is visible before it fails runs

Variant phrasings

CRM API 429 mid sync

A related phrasing for the same underlying problem.

agent no backoff on rate limit

A related phrasing for the same underlying problem.

sync dies on rate limiting

A related phrasing for the same underlying problem.

Compatibility: Compatibility: CRM APIs with documented rate limits (Salesforce, HubSpot) called from agent frameworks, current versions.

Why it happens

A 429 mid-sync is normal operations at scale, and treating it as fatal is the bug. Durable per-account progress plus header-aware backoff converts a hard wall into a slower afternoon, and call-volume reduction keeps the wall further away each run.

Edge cases / pitfalls

• Salesforce and HubSpot express limits differently (daily versus burst). Read the specific API's headers rather than assuming one scheme.
• Jitter matters when several agents share one integration user; synchronised retries recreate the spike.
• Never catch 429 in the same handler as genuine errors. Rate limiting is flow control, not failure.

Provenance

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