API resource limits | Docusign

All Docusign APIs limit each account to a certain number of requests per hour. This number is specified by the X-RateLimit-Limit response header. The limit applies to every request. Hourly API usage refreshes at the top of each hour (for example, 1:00 PM and 2:00 PM). There’s also a shorter, 30-second burst limit that prevents you from making more than 200 calls in the developer environment (or 500 in the production environment) in a very short period of time.

Header	Description
`X-RateLimit-Limit`	The maximum number of requests that can be made in an hour from all apps associated with an account. This value is 3,000 by default. You can update this limit for eSignature API calls through the API limit management feature if your account meets certain prerequisites.
`X-RateLimit-Remaining`	The remaining number of requests for this hour.
`X-RateLimit-Reset`	The timestamp when the rate limit will reset.
`X-BurstLimit-Limit`	The maximum number of API requests you can make in a 30-second burst from all apps associated with an account. This value is 200 in the developer environment, or 500 in the production environment.
`X-BurstLimit-Remaining`	The remaining number of requests for this 30-second span.

See the Resource limits pages for the specific Docusign APIs that your app calls for details.

Note: Unless otherwise documented, Docusign APIs share the same resource limits as the eSignature REST API.

Monitoring your API usage

You can monitor your application’s API usage by checking the X-RateLimit-Limit headers included with most Docusign REST API responses. However, the rate limit headers are not included with all responses, and your code should take this into consideration. If a response doesn’t include a rate limit header, the values that you most recently received are still valid.

The following example shows the API rate limit header fields:

X-RateLimit-Limit: 3000
X-RateLimit-Remaining: 996
X-RateLimit-Reset: 1425967200

Envelope request limits

Accounts are restricted in the number of GET or PUT requests they can make per envelope, per hour. This includes the envelope and all objects that the envelope contains, such as documents.

If your account makes too many GET requests for an envelope in an hour, you may receive an Hourly_Envelope_Polling_Limit_Exceeded error.
If your account makes too many GET requests for an envelope in a 30-second burst period, you may receive a Burst_Envelope_Polling_Limit_Exceeded error.
If your account makes too many PUT requests for an envelope in an hour, you may receive an Hourly_APIInvocation_Envelope_Limit_Exceeded error.
If your account makes too many PUT requests for an envelope in a 30-second burst period, you may receive a Burst_APIInvocation_Envelope_Limit_Exceeded error.

To avoid exceeding these limits and encountering errors, try to use five API calls or fewer when creating or updating the envelope. This includes envelope creation, sending, and any updates. As a best practice, use Docusign Connect to track your envelopes rather than manually making GET calls to poll for their status. If Connect is not available in your infrastructure, limit polling and reduce the rate at which you poll over time.

Individual apps have an additional limit for calls to get envelope status. Apps are limited to one GET status request per unique envelope per 15 minutes. If you exceed this limit, the request will not fail, but it will be flagged as a violation of rate limits, which can cause your app to fail Go-Live review. To avoid exceeding this limit, design your app to poll at 20-minute intervals rather than 15 or, rather than polling for envelope status, your integration can subscribe to Docusign Connect to get status updates for the envelope.

See the eSignature Rules and resource limits page for details.

User info endpoint limits

Docusign limits the number of calls that applications can make to the /oauth/userinfo endpoint. Applications send requests to this endpoint after authentication to obtain the base URI that will be used in subsequent API requests.

These limits apply to /oauth/userinfo requests:

Limit type	Maximum user info requests per hour	Limit applies to
User ID	25,000	The number of user info requests for an authenticated user. An authenticated user is a user whose credentials are supplied during authentication when granting consent for an application to act on their behalf.
Integration key	50,000	The number of user info requests for an integration key. An integration key, also referred to as a client ID, is a GUID value that identifies an integration and is supplied during authentication. An integration key can be used by multiple accounts. This limit applies to the total number of user info requests made under the same integration key for all accounts that use it.

Docusign maintains counts of user info requests per user ID and integration key.These request counts reset to zero at the top of every hour.

If your application sends a user info request and the requests for that user ID or integration key have exceeded the per-hour maximum, Docusign returns the HTTP status code 429 Too Many Requests with this error information:

{
  "error": "principal_throttled",
  "error_description": "You have exceeded the maximum number of requests for this time window. Please try again later.",
  "reference_id": "[reference ID]"
}

If you need to contact Docusign Support for assistance, include the reference_id with your support request.

Next steps

See the eSignature REST API rules and resource limits.
Learn how to Go-Live to move your integration into the production environment.