Clearer Docusign API error message and status code improvements

Docusign is rolling out a set of improvements to error messages and HTTP status codes for resource limit scenarios across our platform. These changes make it easier to understand what failed, why it happened, and how to fix it.

This post explains what changed across three areas (error message clarity, HTTP status code alignment, and a new send-limit error) and walks through how to assess whether your integration is affected and what steps to take if it is.

Key takeaways

• 16 API error messages across document, envelope, recipient, and usage limit scenarios now include clear, actionable language: what failed, why it happened, and how to fix it.

• API rate-limiting errors (hourly and burst limits) now correctly return HTTP 429 instead of 400, making them compatible with standard backoff and retry libraries.

• Cumulative recipient limit errors now return HTTP 400 instead of 429, correctly reflecting account configuration constraints rather than throttling behavior.

• A new error, ENVELOPE_SEND_LIMIT_EXCEEDED, separates send limit enforcement from billing errors.

• If your integration parses the errorCode field, you likely don't need to make changes. If you rely on exact error message strings or hardcoded HTTP status code assumptions for rate limits, plan a test pass now.

What’s changing

1. Clear, actionable error messages

Sixteen API error messages have been updated across document, envelope, recipient, and usage-limit scenarios. The new messages are standardized to clearly communicate:

• What went wrong 

• Why it happened

• How to resolve it

For example, the previous DOCUMENT_LIMIT_EXCEEDED message read: “The document limit on the envelope has been exceeded.” 

Now, the message reads: “You have reached the maximum number of documents allowed in a single transaction. You can send up to 130 documents in a single transaction.”

This change makes the same error immediately actionable without needing to read documentation or look up other resources. 2. Consistent HTTP status codes for rate-limiting errors

Several limits-related errors are moving to HTTP status codes that better reflect their meaning in standard HTTP semantics.

Cumulative recipient limit errors (such as RECIPIENT_LIMIT_EXCEEDED in cumulative scenarios) now return 400 Bad Request instead of 429 Too Many Requests, because they reflect account-level configuration and transaction composition rather than throttling.

API rate limiting and polling errors now return 429 Too Many Requests instead of 400 Bad Request, because they represent throttling behavior where a retry after a delay is appropriate.

For example, hourly and burst rate limits for polling and API calls now consistently return status code 429, and the response text tells you that you’ve hit a limit and should try again later, and to use a webhook, if you aren’t already.

This alignment means you can plug Docusign into standard retry libraries and backoff strategies that already treat 429 as a rate-limit signal.

3. New error for send limits

A new error code, ENVELOPE_SEND_LIMIT_EXCEEDED, now handles cases where an account exceeds its configured send limit within a rolling multi-day window.

This new error returns a 400 status code with the message:

 “This account has reached its send limit within a ####-day period. Please try again in a few days, or ask your administrator for help.”

How these changes affect existing integrations

For most integrations, this transition should be smooth. However, there are a few cases where you might see behavior changes worth testing for

Safe by default: integrations that parse errorCode

If your integration handles errors by parsing the errorCode field in the response and using that value to branch logic (for example, deciding whether to retry, showing a specific message, or escalating), you don’t need to make any structural changes. These updates are non-breaking for integrations that key off errorCode rather than matching error message strings or assuming specific HTTP status codes for rate limiting scenarios.

Validating in lower environments is still recommended, but you shouldn’t need to refactor to your error handling.

Potentially impacted: string matching and hardcoded status assumptions

Your integration may be affected if it:

• Performs exact string matching on errorMessage (for example, if (errorMessage == "The document limit on the envelope has been exceeded"))

• Assumes that specific limits-related conditions always return HTTP 400 instead of 429, or vice versa, and uses only the status code to make retry decisions

In those cases, the new messages and status codes may cause:

• Certain conditional checks to stop firing

• Retry logic to change behavior (for example, if you previously treated all 400s as non-retryable and all 429s as retryable)

• Monitoring dashboards or alert thresholds that are keyed off status codes to show different distributions

If that sounds like your integration, plan on a test pass and possibly a targeted refactor.

How to get started

Availability: This update applies to all Docusign accounts, plans, and environments. No configuration is required since changes are applied automatically.

Rollout schedule: The developer environment is now updated. The production rollout is in progress and is expected to be completed in July 2026.

Recommended steps before production rollout completes:

1. Review your error handling logic. Check whether you match on errorMessage strings or use hardcoded HTTP status code assumptions for rate-limit scenarios.

2. Update your logic to key off instead of message strings.

3. Confirm that 429 responses trigger backoff and retry behavior in your integration.

4. Validate your flows in the developer environment, where the changes are already live.

If you need additional time to update your integration, work with your Docusign support or customer success contact to request an extension. 

Full list of updated error codes and messages

The table below shows all updated errors. "HTTP status" columns refer to the HTTP response code returned. Error names (codes) are unchanged unless noted.

Frequently asked questions

Are any API limits changing as part of this update?

No. This update does not change any underlying system limits such as envelope size, document count, page count, or API call volume. Only the error message text and HTTP status codes are changing.

Will this break my existing integration?

It depends on how your integration handles errors. If you parse the errorCode field and use value to drive your logic, you should be unaffected. If your integration relies on exact errorMessage string matching, or assumes that rate-limiting conditions always return 400 rather than 429, you may see behavior changes and should plan to test and update your code.

How can I tell if I need to make changes?

Review your error handling logic for three patterns:

• Exact matching on errorMessage strings

• Using only the HTTP status code (400 vs 429) to decide when to retry

• Monitoring or alerting thresholds that are keyed to specific status code distributions 

If you find any of those patterns, update your logic to key off errorCode, treat 429  as a rate limit signal with backoff and retry, and validate your flows in demo before the production rollout completes.

What if I need more time to update my integration?

If you need additional time, work with your Docusign support or customer success contact to request an extension. 

Next steps

The developer environment already reflects all of the changes described in this post, so you can test your error handling behavior there today.

As the production rollout completes, review your integration using the guidance in the "How these changes affect existing integrations" section above.

If you encounter error responses where more clarity would still help, share your feedback (or questions) with Docusign by adding a comment on this Community thread.