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_Exceeded

• Burst_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 hour

• Burst_APIInvocation_Envelope_Limit_Exceeded: Too many envelope updates (PUTs) in the last 30 seconds

• Hourly_Envelope_Polling_Limit_Exceeded: Too much envelope polling (GETs) in the last hour

• Burst_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. 

Additional resources

• API resource limits

• Docusign Developer Center

• Docusign for Developers on YouTube

• @DocuSignAPI on Twitter

• Docusign on Twitch

• Docusign For Developers on LinkedIn

• Docusign Developer Newsletter