Service protection: New API errors for excessive polling and envelope updates
DocuSign has implemented automatic checks to ensure that eSign API applications that excessively poll or update envelope objects will receive an error response.
Background: DocuSign’s API usage guidelines require applications to limit how often they request information about an envelope. The guidelines also require efficient use of the DocuSign APIs.
By design, DocuSign is not providing the exact limits and algorithms used to detect excessive polling (get and list methods via the HTTP GET verb) for envelopes and their subsidiary objects (the envelope’s fields, documents, recipients, etc). Similarly, the exact limits and algorithms for detecting excessive envelope updates (HTTP PUT calls) will not be published. Updates to the base envelope object and its subsidiary objects are tracked.
The limits are implemented per envelope ID for the eSign REST API versions 2, and 2.1. The limits are implemented for both the development (demo) and production environments. Each type of operation (excessive polling and updates) is checked on both a sliding 30 second window and on an hourly basis.
Today, two new error codes will be returned along with a 400 status when an error is detected:
Hourly_APIInvocation_Envelope_Limit_ExceededBurst_APIInvocation_Envelope_Limit_Exceeded
Today, these errors indicate that either an excessive polling or excessive envelope updates error has occurred on an hourly or burst (30 seconds) basis.
Starting with the June 2022 release, the error codes will be refined and additional error codes will be added to enable easier troubleshooting:
Hourly_APIInvocation_Envelope_Limit_Exceeded: Too many envelope updates (PUTs) in the last hourBurst_APIInvocation_Envelope_Limit_Exceeded: Too many envelope updates (PUTs) in the last 30 secondsHourly_Envelope_Polling_Limit_Exceeded: Too much envelope polling (GETs) in the last hourBurst_Envelope_Polling_Limit_Exceeded: Too much envelope polling (GETs) in the last 30 seconds
Fixing problems
- For excessive polling, consider implementing Connect webhooks instead of polling.
- For excessive envelope updates, combine envelope update calls into fewer calls that include more data updates.
