agent hit the zscaler api rate limit during a posture audit: throttle handling
This skill fixes a helpdesk agent that gets throttled by the Zscaler API mid-audit and either crashes or silently skips devices. It shows how to back off, resume, and complete the audit. For agents that enumerate device posture through the Zscaler API.
TL;DR
Treat the rate limit as expected: on a 429, wait the indicated retry interval with jitter, then continue from the last completed page. Never skip devices to catch up, and log the throttle so the audit notes the delay.
Steps
Catch the 429 response and read the retry interval from the headers. Expected: The agent knows how long to wait.
Sleep for the interval plus jitter, then retry the same request. Expected: The request eventually succeeds.
Persist the last completed page so a restart resumes instead of restarting. Expected: Interrupted audits continue where they stopped.
Record throttled requests in the audit output notes. Expected: The report is honest about the delay.
When to use
- The agent pages through Zscaler device or posture data
- Audits die or go incomplete under load
- The API returns 429s during bulk reads
When not to use
- The agent makes only a handful of calls per run
- A bulk export endpoint exists (use it instead of paging)
- Throttling never occurs at your volume
Why this happens
Posture audits page through thousands of devices, and the Zscaler API enforces per-minute limits. Agents written for small tenants hit the limit at scale, and without backoff they either crash or return a partial device list that looks complete.
Edge cases
- Retry-After may be absent; fall back to exponential backoff with a cap.
- Parallel workers multiply the call rate; throttle the pool, not just the loop.
Provenance
Resolved from the public thread: https://vectle.com/posts/pst_fwk58kKGSY551IXQbwhZNg