From the Trenches: API rate limits
From time to time, customers contact Developer Support because they encounter this error: HOURLY_APIINVOCATION_LIMIT_EXCEEDED. To maintain reliability and stability within our demo and production environments, DocuSign operates with certain API rate limit guidelines. Performance isn’t the only reason to limit API requests: rate limiting is an essential component of Internet security, as DoS attacks can crash a server that permits unlimited API requests.
API hourly rate limits and 30-second burst limits
DocuSign has implemented the following default API rate limits to keep processing demand within our platform limits:
- By default, both the developer (demo) and the production environments are limited to a call rate of 3,000 API calls per hour per account.
- A shorter 30-second burst limit (500 calls) has also been implemented that prevents large numbers of calls in very short periods of time, but should not affect most of existing integrations.
- For more information on API rules and limits, please see API Resource Limits.
Checking your API usage
You can monitor your API usage by checking these headers with most DocuSign API responses.
| Header Name | Description |
|---|---|
| x-ratelimit-limit | the rate limit permitted to make per 60 minutes |
| x-ratelimit-remaining | the number of requests left for the 60-minute window |
| x-ratelimit-reset | the remaining window before the rate limit resets |
| x-burstlimit-limit | the short burst limit permitted for 30 second window |
| x-burstlimit-remaining | the number of requests left for the 30-second window |
When an API call limit is exceeded, you will receive an exception for each additional call until the start of the next hour. The exception message states:
{
"errorCode": "HOURLY_APIINVOCATION_LIMIT_EXCEEDED",
"message": "The maximum number of hourly API invocations has been exceeded. The hourly limit is 3000."
}
When an burst call limit is exceeded, you will receive an exception for each additional call until the start of the next burst window. The exception message states:
"BURST_APIINVOCATION_LIMIT_EXCEEDED"
The reset time is shown in Unix epoch time. For more information, see our REST API Guide: Requests & Responses. If you're using an SDK, see our blog post, Working with Headers in DocuSign SDKs.
API resource polling restrictions
For polling compliance, DocuSign requires that you do not exceed one unique resource request per 15 minutes. Examples of unique resource requests are: retrieving an envelope's status, retrieving documents from a specific envelope, checking a specific recipient status for a specific envelope, etc. There are a number of ways to minimize API impact.
Ways to reduce the number of API calls
- Using bulk operations to request status A common pattern we see is:
- A call to list Envelopes
- Iterating through the list with a call to each of the following:
- A call to get the details of a particular envelope
- A call to get that envelope’s recipients
- A call to get that envelopes documents
GET https://demo.docusign.net/restapi/v2.1/accounts/$account/envelopes?from_date=2020-01-15T00:00:00Z&from_to_status=any&status=any&include=recipients,documents
The result is a list of envelopes with the recipient and document nodes included. This pattern can save hundreds of API calls. Below is an example recipient returned:
"recipients": { "signers": [ { "signInEachLocation": "false", "creationReason": "sender", "requireUploadSignature": "false", "name": "Geoff Test", "email": "user@company.com", "recipientId": "1", "recipientIdGuid": "9dadbed4-xxx-xxxx-xxx-3b0cbbb9ef70", "requireIdLookup": "false", "userId": "dcce8b59-xxxx-xxxx-xxxx-987afe3f7", "routingOrder": "1", "roleName": "Sales", "status": "completed", "completedCount": "1", "signedDateTime": "2020-01-15T21:04:38.1030000Z", "deliveredDateTime": "2020-01-15T21:04:28.4930000Z", "deliveryMethod": "email", "recipientType": "signer" },And this shows an example document returned with its first page:
"envelopeDocuments": [ { "documentId": "1", "documentIdGuid": "60ada10c-xxxx-xxxx-xxxx-b6f13ab19433", "name": "Document Packet.pdf", "type": "content", "uri": "/envelopes/658e5a95-xxxx-xxxx-xxxx-74160b41fdd2/documents/1", "order": "1", "pages": [ { "pageId": "44430677-xxxx-xxxx-xxxx-7e295d37122d", "sequence": "1", "height": "792", "width": "612", "dpi": "72" }, - Refraining from repeatedly requesting information on envelopes that are in terminal status (completed, declined or voided) This information can be cached or stored in a database.
- Using Connect, DocuSign’s event notification service DocuSign Connect is a service that offers proactive notification capabilities. The Connect service uses webhooks for notifications on changes to your application. The notifications could be about status changes for envelopes, recipient changes and much more. More information to help configure and manage the service can be found in our Administration Guide.