Service protection: New API errors for excessive polling and envelope updates

Larry Kluger

DocuSign Lead Product Manager for Partner Platforms

•

Summary•2 min read

Docusign has implemented two new error codes to explicitly indicate that your integration has violated hourly and burst API calling limits.

- Fixing problems
- Additional resources

Table of contents

Fixing problems

Additional resources

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.