# Fix DocuSign RATE_LIMIT_EXCEEDED when polling envelope status

## TL;DR
You're burning through DocuSign's hourly API budget (default 1,000 calls per rolling hour per account) by polling envelope status in a loop. Pause the polling, back off with jitter until the reset window passes, and replace polling with DocuSign Connect webhooks that push status changes to you. Polling is the classic way to hit this limit; event-driven is the supported pattern.

```text
RATE_LIMIT_EXCEEDED
```

## Steps
1. Confirm the 429 and read the reset time from the response headers (X-RateLimit-Reset).
   Expected: a 429 response with a reset timestamp, usually minutes out, confirming this is rate limiting and not auth.
2. Stop the poll loop immediately and implement exponential backoff with jitter on any retries.
   Expected: no new calls go out until after the reset time; the 429s stop.
3. Set up a DocuSign Connect configuration that POSTs envelope events (sent, delivered, completed, declined) to your listener endpoint.
   Expected: status changes arrive as webhook events; your polling call volume drops to near zero.
4. Cache the last known status per envelope and only re-check on a schedule that fits your budget, for example a slow sweep for stuck envelopes.
   Expected: steady-state API usage stays well under the hourly cap.
5. If legitimate volume still exceeds the cap after going event-driven, request a limit increase from DocuSign support with your account ID and call pattern.
   Expected: support confirms a higher hourly budget for the account.

## Use this when
- Envelope status polling starts returning 429 RATE_LIMIT_EXCEEDED
- A batch job or sync loop hammers the envelopes endpoint on a timer
- You're designing an integration and want to stay under DocuSign's call budget

## Not for this skill when
- You're getting 401/403 errors (that's authentication, not rate limiting)
- A single call fails intermittently without 429s (that's a transient error; retry with backoff)
- You're hitting limits on a different API (each provider has its own budget and headers)

## Variant phrasings
### docusign api 429 too many requests polling
Same fix: back off, then move to Connect webhooks.
### docusign rate limit exceeded envelopes endpoint
The envelopes status endpoint is the usual budget-killer; cache aggressively.
### increase docusign api rate limit
Possible via support, but fix the polling pattern first or you'll burn the higher budget too.

## Why it happens
DocuSign meters API calls per account on a rolling hourly window plus short burst limits. Status polling is the worst pattern for this: N envelopes times a poll interval quickly exceeds the budget, and every poller instance multiplies it. Connect webhooks invert the flow so DocuSign calls you only when something changes.

## Edge cases
- Demo and production accounts have different limits; load-test against the right one.
- Each poller replica counts against the same account budget; one forgotten staging worker can eat it.
- Connect needs a publicly reachable HTTPS endpoint and a replay plan for missed events; keep a slow reconciliation sweep as a safety net.
- Bursts (for example, 500 envelopes completing at once) can trip the short-window limit even with webhooks; queue and pace the follow-up calls.

## Provenance

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