From the Trenches: Deep dive into Docusign Connect's error codes

Docusign Connect is used by customers around the world to deliver updates to a webhook listener. These can range from anything to status updates on the envelope, progress of the envelope’s recipients through the envelope, or even delivery of the signed documents once the envelope is complete. 

Sometimes, due to certain issues encountered during the delivery of a Connect webhook event, the delivery might fail. Often, this is temporary, and the message will be retried either automatically or through a manual republish and will subsequently be successfully delivered. When this event fails, an error message is logged. These errors can be viewed on the Connect dashboard. In this blog, I will explain some of the most common errors and their potential causes. 

400 - Bad Request

This is one of the most common errors that occur with Docusign Connect messages. This indicates that Connect’s messages reached your listener, but the listener would not process it due to the listener believing that there is a syntax error in the Connect message. 

The most likely explanation for this is that your listener was expecting the message to be in a different format than what was received. We recommend that your listener is configured to accept messages that match Connect’s schema.

401 - Unauthorized

The 401 Unauthorized response code indicates that the listener refused to accept the Connect message because it was missing valid authorization credentials, usually in the form of an Authorization Header. This response also includes an HTTP WWW-Authenticate header that contains information on the type of authentication the listener expects Docusign to include to make the request successfully. 

To fix this, you might have to configure OAuth 2.0 for Docusign Connect and configure your authorization server so that Docusign may obtain an access token to include in the Connect message’s header that your listener can then validate. 

403 - Forbidden

The HTTP 403 - Forbidden response is used when a server (your Docusign Connect listener in this instance) receives a request (the Docusign Connect message), understands it, but refuses to process it. 

The likely cause for this is tied to application logic on your listener, such as it having insufficient permissions to a resource or action that is required for the successful processing of your Connect message.

404 - Not Found

This error means that Docusign Connect is either unable to reach the specified endpoint for your configuration or that the endpoint doesn’t exist. 

The most likely reason for this is that your endpoint is behind a firewall that is blocking Docusign Connect’s messages to your listener. Your Connect listener must be on the open internet or your firewall must be configured to allow Docusign’s IP Addresses 

405 - Method Not Allowed

The HTTP 405 - Method Not Allowed error indicates that the server (your listener) knows the request method, but doesn't support this method. 

Docusign Connect’s messages are sent as HTTP POST requests to your listener, so make sure that your listener is configured to accept HTTP POST requests.

413 - Request Entity Too Large

This error means that your listener received Docusign Connect’s message, but the size of that message was larger than the size limit defined by your listener.

This can happen when your configuration is defined to include the envelope documents in the Connect message. For particularly large envelopes with many documents, the payload size can grow large enough to trigger this error. We recommend not including the documents in your Connect configuration, but instead using the Connect message as a trigger to make an API call to Docusign and download the documents as needed. 

500 - Internal Server Error 

The 500 - Internal Server Error indicates that your listener received the Connect event, but ran into an unexpected error while trying to process it. This could happen for any reason and would need to be diagnosed on your server to understand what went wrong.

Error - The operation has timed out

While this is not an error that would be returned by your listener, this is an error that can be logged as part of the Connect message transmission. This is usually caused by Docusign trying to contact your listener, but not receiving any response in 100 seconds, after which it times out and logs this error message. 

If you would like further information on any of these or any other errors your Connect listener is experiencing, please feel free to reach out to our support team or reach out to us via the Docusign Community.