From the Trenches: Capturing API errors
If something's gone wrong in your application's workflow, but you don't have proper error handling, it can be difficult (or even impossible) to tell what's broken and what needs to be done to resolve the problem. For this reason, it's important to plan how your application will handle, log and report errors, both in a DocuSign API and elsewhere. DocuSign provides some tools to help, but ultimately the choice on how to use them is up to you as the application developer.
First, let's start by breaking down what an error may look like. Let’s suppose I've set up an application that adds a recipient to an envelope, but for this particular envelope, the recipient isn't being added. When I investigate the problem, at the most basic level, I can see the call to the eSignature API is returning a 400 - Bad Request response, so I know something is wrong, but I'll need to dig deeper to determine what. While the HTTP response code can tell you something is broken, it will rarely tell you anything beyond that.
Next, I decide to parse out the response body to find there's both an ErrorCode and a Message. In this case my ErrorCode is EDIT_LOCK_INVALID_STATE_FOR_LOCK, which seems strange:I wasn't attempting to lock an envelope, I just wanted to make a single change!
Fortunately, the Message clarifies: Failed to acquire the lock because the envelope status was not 'created', 'sent' or 'delivered'. I now have reason to believe the call failed because the envelope is not in a status that will allow me to modify it. With this information, I can check the envelope and find that it is in "Declined" status: the recipient has terminated the envelope, so I can no longer make changes to it.
In some cases (most commonly, authentication-related failures) there can also be a reference_id. If you are engaging DocuSign Support and have a reference_id or an X-DocuSign-TraceToken, those values may assist the support representative in identifying telemetry related to your API call.
For this example, I was in a simple testing environment where the response body was readily available. In a more complex production environment, that may not be the case. While the specifics of how to expose errors will depend on your application's architecture, tools are available that can track traffic at the network level, outside of your application. One commonly-used example is Telerik’s Fiddler.
As there is plenty of documentation out there on the specifics of how to use Fiddler in various scenarios, I'll keep this section brief. DocuSign APIs all require the use of HTTPS, so you will need to set Fiddler to decrypt HTTPS traffic. Some development environments don't take to this natively. For example, in Eclipse for Java, not only do you need to configure the IDE to use Fiddler's proxy, you also need to create a Keystore and trust the Fiddler Root Certificate.
While there are some hurdles to clear regardless of your implementation, there's certainly value in seeing traffic you otherwise may be missing.
Finally, you shouldn't discount the value of API logging. While the DocuSign API logs only capture eSignature API traffic that is successfully authenticated and directed to a valid endpoint, they are a handy resource as well.
