Blog
Home/

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

Larry Kluger
Larry KlugerDocuSign Lead Product Manager for Partner Platforms
Summary3 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

          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

          Larry Kluger
          Larry KlugerDocuSign Lead Product Manager for Partner Platforms

          Larry Kluger has over 40(!) years of tech industry experience as a software developer, developer advocate, entrepreneur, and product manager. An award-winning speaker with a 48K StackOverflow reputation, he enjoys giving talks and helping the ISV and developer communities.

          Twitter: @larrykluger

          LinkedIn: https://www.linkedin.com/in/larrykluger/

          More posts from this author

          Related posts

          • Developers

            What Are API Services? Benefits & Uses

            Docusign Contributor
          • Fast-Track Your Extension Apps with Reference Implementations

            Karissa Jacobsen
            Karissa Jacobsen
          • Paige Rossi
            Paige Rossi

          Fast-Track Your Extension Apps with Reference Implementations

          Karissa Jacobsen
          Karissa Jacobsen
          Paige Rossi
          Paige Rossi

          Discover what's new with Docusign IAM or start with eSignature for free

          Explore Docusign IAMTry eSignature for Free
          Person smiling while presenting