Back to Docusign.com
Overview
For those familiar with Docusign’s API Rules and Limits, you’re probably already aware of some of the error messages that Docusign returns when using our various APIs. These typically exist in the form of response headers, HTTP response status codes, or specific error messages contextually related to your current activities. If, for example, you had previously run into hourly limits, you may already be aware of Ratelimit-Remaining or Hourly / Burst limits, among others.
Recently, we have redesigned several commonly encountered API error messages to be more intuitive and customer-friendly. Historically, many of these messages were overly technical, ambiguous, or lacked clear next steps, often leading to confusion, increased support tickets, and slower issue resolution.
In addition to message improvements, we have updated select HTTP status codes to better align with standard API conventions:
- Changed from 429 → 400 for cumulative recipient limit errors (RECIPIENT_LIMIT_EXCEEDED)
- Changed from 400 → 429 for API rate limiting and polling related errors (hourly and burst limits)
These improvements are designed to create a more consistent and predictable error handling experience across APIs, reduce developer friction when integrating with Docusign APIs, and decrease reliance on Support for common issues.
No changes were made to the underlying limits or enforcement behavior.
Please see below for a full list of updates to Error response codes and messages.
How critical are these changes? Do we need to take action?
These changes are critical for any API-based integration that relies on specific HTTP response codes or error messages. The nature of eSign makes it necessary to track current applicable limits and to be aware of when cutoffs occur. The previously trackable Ratelimit-Remaining are remaining in place for you to tell when you’re approaching your current platform limits.
If, for example, your integration is configured so it expects to see the following and is presently tracking by status code or error message:
400 - HOURLY_APIINVOCATION_LIMIT_EXCEEDED
“The maximum number of hourly API invocations has been exceeded. The hourly limit is ###.”
It will need to be adjusted to look for:
429 - HOURLY_APIINVOCATION_LIMIT_EXCEEDED
“Your account has reached the maximum permitted hourly limit of #### API requests. Try again in 1 hour.”
The best practice to avoid this from happening is to monitor Limit-Remaining response headers so that you know to reduce traffic and avoid an overage. Running into your limits and not being able to react may result in delays processing agreements and workflows.
If you have any questions or would like assistance with understanding these changes, please reach out to your Account Representatives and to Docusign Customer Support where one of our representatives will be happy to assist you.
When do we need to update?
The new error messages and codes will be released during the following timeframes:
- Demo: May 14th, 2026 to May 16th, 2026
- Production: June 1st, 2026 to June 9th 2026
List of Updated Errors:
| Error Name | [Current] Error Code | [Current] Error Message | [New] Error Code | [New!] Error Message |
| COMBINED_DOCUMENT_SIZE_OVER_LIMIT | 400 | An error occurred while downloading the document. Try downloading the documents in a .zip file Total size of all documents being downloaded exceeds the allowed limit: 100MB. Please try to single download each documents | No change | Documents being downloaded exceed the allowed limit of 100 MB. Try downloading all your agreements as a .zip file, or download each file individually. |
| DELIVERY_METHOD_RECIPIENT_LIMIT_EXCEEDED | 400 | The limit on recipients with a specific delivery method has been exceeded. An envelope cannot have more than 10 SMS/WhatsApp recipients. | No change | You can choose up to #### SMS or WhatsApp recipients per send. |
| DOCUMENT_LIMIT_EXCEEDED | 400 | The document limit on the envelope has been exceeded. | No change | You have reached the maximum number of documents. You can send up to 130 documents in a single transaction. |
| DOCUMENT_SIZE_LIMIT_EXCEEDED | 400 | The total document size on the envelope has exceeded the allowed limit. | No change | You have reached the maximum upload limit allowed for a single transaction. The total size of all uploaded documents cannot exceed 200MB. |
| FORMAT_CONVERSION_ERROR | 400 | The data could not be converted. The document is too large. | No change | One or more documents uploaded exceeds the maximum allowed single file size limit of 50 MB. You can make your document(s) smaller or break up the document(s) into multiple parts. |
| Document_Contains_Too_Many_Pages | 400 | The PDF's page count, {user upload page count} exceeds the limit: 2000 | No change | One or more documents exceeds the maximum page limit of 2000 pages. You can make your document(s) smaller or break up the document(s) into multiple parts. |
| API_REQUEST_IS_THROTTLED | 429 | [API Action name, for example GetDocument / PutDocument] call blocked | No change | We blocked your [API Action Name] call, because a similar request is already in progress. Try again after your current request completes. |
| ENVELOPE_DRAFT_LIMIT_EXCEEDED | 400 | The maximum number of envelope drafts for the account has been exceeded. Please send or delete some drafts, and try again. | No change | Your Drafts folder is full. Please Send or Delete draft transactions to re-enable the ability to save more drafts. |
| HOURLY_APIINVOCATION_LIMIT_EXCEEDED | 400 | The maximum number of hourly API invocations has been exceeded. The hourly limit is ###. | 429 | Your account has reached the maximum permitted hourly limit of #### API requests. Try again in 1 hour. |
| HOURLY_ENVELOPE_POLLING_LIMIT_EXCEEDED | 400 | The maximum number of hourly polling calls for the envelope has been exceeded. The hourly limit is 250. | 429 | Your account has reached the hourly limit of #### polling calls. To prevent this from happening again, enable webhooks to allow for real-time, automatic updates. |
| Hourly_APIInvocation_Envelope_Limit_Exceeded | 400 | The maximum number of hourly API invocations for the envelope has been exceeded. The hourly limit is ###. | 429 | Your account has reached the maximum permitted hourly limit of #### API requests. Try again in 1 hour. |
| BURST_APIINVOCATION_LIMIT_EXCEEDED | 400 | The maximum number of burst API invocations has been exceeded. The burst limit is #### | 429 | Your account has reached the maximum permitted limit of #### API requests. Try again in 1 minute. |
| BURST_ENVELOPE_POLLING_LIMIT_EXCEEDED | 400 | The maximum number of burst polling calls for the envelope has been exceeded. The burst limit is ### | 429 | Your account has reached the limit of #### polling calls. To prevent this from happening again, enable webhooks to allow for real-time, automatic updates. |
| Burst_APIInvocation_Envelope_Limit_Exceeded | 400 | The maximum number of burst API invocations for the envelope has been exceeded. The burst limit is #### | 429 | Your account has reached the maximum permitted limit of #### API requests. Try again in 1 minute. |
| RECIPIENT_LIMIT_EXCEEDED | 429 | The cumulative recipient limit has been exceeded. | 400 | You have reached the maximum number of recipients permitted for a single transaction in your account. Please ask your administrator to increase your limit. |
| RECIPIENT_LIMIT_EXCEEDED | 400 | The recipient limit on the envelope has been exceeded. | No change | You have reached the maximum number of recipients allowed for a single transaction. Please remove some recipients, or split them across multiple transactions. |
| ENVELOPE_ALLOWANCE_EXCEEDED | 400 | The envelope allowance for the account has been exceeded. Note: The billing error code was incorrectly firing when the service protection limit exceeded. With this change, we have created a new error to handle service protection limits, called “ENVELOPE_SEND_LIMIT_EXCEEDED” (see below). | No change | This account is out of credits. Ask your administrator to add more. |
| ENVELOPE_SEND_LIMIT_EXCEEDED **Note: this is a new error** | N/A | N/A | No change | This account has reached its send limit within a ####-day period. Please try again in a few days, or ask your administrator for help. |
Frequently Asked Questions:
Q: Will this break my customer’s integration?
A: It depends on how their integration is built. It will not break integrations that follow best practices (parsing the errorCode attribute). However, it will break integrations if the customer has hardcoded logic that looks for specific error message strings (e.g., if errorMessage == "The document limit on the envelope has been exceeded"). It may also impact logic if they explicitly check for a 400 status code on rate limits instead of a 429.
Q: Will this break my customer’s integration?
A: It depends on how their integration is built. It will not break integrations that follow best practices (parsing the errorCode attribute). However, it will break integrations if the customer has hardcoded logic that looks for specific error message strings (e.g., if errorMessage == "The document limit on the envelope has been exceeded"). It may also impact logic if they explicitly check for a 400 status code on rate limits instead of a 429.
Q: Why are we changing status codes from 400 to 429?
A: A 400 Bad Request usually means the payload was formatted incorrectly. A 429 Too Many Requests is the internet standard for rate limiting. Moving to 429 allows customers to use standard exponential backoff and retry libraries rather than writing custom logic.
Additional resources
- API changelog (mapping table and rollout dates)
- Developer docs — error handling best practices
- Contact Docusign Support
Join the conversation
Have you run into any unexpected behavior after these updates or need help updating your client logic? Drop a comment below with your use case or ask for an example snippet — we’ll help you map the new responses into a robust error‑handling strategy.