From the trenches: Concurrency issues

•

Summary•3 min read

In general an integration is free to make many API calls nearly simultaneously, but there are a few cases where concurrent requests can run into trouble

While in general an integration is free to make many API calls nearly simultaneously, there are a few cases where concurrent requests can run into trouble:

Burst API Limit: Docusign has a system-wide burst limit of 500 API calls over 30 seconds. If a particular account exceeds this threshold, further API calls made in that short window will be blocked.

Concurrent Envelope Updates: An integration can make calls to update several envelopes at once, but if multiple actions are taken on the same envelope at the same time, problems can arise. For example, if your integration begins uploading a document to a draft envelope and also makes attempts to add a recipient before the upload is complete, the changes may not process correctly. For this reason, you must ensure API calls made against the same envelope happen sequentially: only firing once the previous call against that envelope has completed.

If multiple integrations will be used on a single account, Envelope Locking can be used to ensure they do not conflict by modifying an envelope at the same time.

Multiple Signing Sessions: Similar to updating envelopes: An integration can have several embedded signing sessions taking place at once, but only one signing session per envelope. If multiple recipients need to sign a single envelope, they'll need to do so one at a time. In this case, requesting a second signing session URL will invalidate the first. If the first signing session is already active, they will be kicked out and data entered may be lost. For this reason, your application should wait for the first signer to be directed to the landing page before subsequent signing sessions are generated.

Thread-safety Concerns: At the time of writing, there is a known issue with the C# client library: ApiClient objects are not thread-safe, and configuration changes made in one (such as setting an Authorization header) may overwrite others. This means that if you are building a multi-user application running multiple simultaneous sessions, special care needs to be taken to ensure that calls are made using the correct authentication token. Otherwise, actions taken by one user could be done under the name of another.

One method that is notable in this case is RequestJWTUserToken(). Executing this method will cause all apiClient objects instantiated by your application to use the token generated—not just the particular apiClient used to call the method.

As always, we strongly recommend testing using your developer account prior to release. Identifying areas of concern early can prevent errors with live envelopes.