Skip to navigation
SDKsC# SDK

Calling C# SDK methods and handling errors

View as Markdown

Calling methods

Making API calls through the C# SDK requires calling defined methods in classes in the DocuSign.eSign.Api namespace. Each of these classes corresponds to a group of endpoints that are used for specific feature areas related to the Docusign eSignature REST API.

Each specific REST endpoint typically has four or more different C# SDK methods that can be used to call it. As an example, here are four methods that call the endpoint "/v2.1/accounts/{accountId}/brands/{brandId}"``:

    accountsApi.UpdateBrand(accountId, brandId, brand);
    accountsApi.UpdateBrandAsync(accountId, brandId, brand);
    accountsApi.UpdateBrandWithHttpInfo(accountId, brandId, brand);
    accountsApi.UpdateBrandAsyncWithHttpInfo(accountId, brandId, brand);

The differences between these four methods are the information they return and whether they make the call on the calling thread or in a separate background thread. It’s important to note that each of the four methods above call the same API endpoint.

The first method, UpdateBrand, which is considered the most simple approach, makes the API call from the same calling thread synchronously, blocking it until the call is complete. It will only return the Brand object that represents the JSON object that is being sent back from the API.

The second method, UpdateBrandAsync, uses the C# concurrency library and returns a generic System.Threading.Tasks.Task<Brand> object. This object represents a parallel C# task that can be run independently of the main thread and can signal the main thread when it completes. At that point, the object of type Brand will be ready to be consumed by the main thread. This approach is recommended when the API call is made from a UI, and the UI is blocked until the API call is complete. It enables the developer to make API calls in parallel and continue the main UI thread to improve the user experience.

The third (UpdateBrandWithHttpInfo) and fourth (UpdateBrandAsyncWithHttpInfo) methods are variants on the first and second methods that return additional information. These methods return the generic ApiResponse<Brand> class, which provides both the data from the body of the HTTP response (the JSON) as a generic object (in this case, Brand) as well as the status code and the collection called Headers that includes all the HTTP headers in the response. These are useful to get additional information from the API—for example, information about API request limits—that lives in the HTTP headers of the response.

Handling errors

Error handling is an important part of developing your software. Your code should handle both expected and unexpected errors.

The C# SDK provides an ApiException class that is used for common scenarios where exceptions are thrown. It’s a best practice to catch this exception in your code and inspect the ErrorCode and ErrorMessage objects to provide useful information to understand the cause of the error.

Common scenarios where the SDK throws an ApiException are:

  • Invalid or expired access token.
  • HTTP response status code 400 and above. These represent various error messages that are identified by the HTTP layer. Such errors include not authorized (403) errors, which occur due to issues with authentication.
  • Issues in deserialization of the response JSON. If the JSON sent back by the API cannot be properly deserialized into the C# objects that the SDK is expecting, an ApiException is thrown, and the “bad” JSON is returned in the ErrorMessage property of the exception.
  • JWT issues with either the private RSA key pair or userId. Since the RequestJWTUserToken method for obtaining an OAuth token using JWT is included in the SDK, an ApiException is thrown if the RSA key or userId are missing or malformed.

Troubleshooting for common errors has detailed information about causes and resolutions for specific errors.

Obtaining the trace token for solving problems via Support

Every API response includes a GUID that can be used to trace it on the back end by Docusign Support. This GUID is called the trace token. The trace token enables Support staff to find the internal logs in the system related to the API request/response and to get additional information about it. This information may not be directly available to developers with or without the SDK.

The trace token is part of the HTTP response header. To obtain the trace token, you will first call the WithHttpInfo variant of the method to retain the header of the HTTP response.

    ApiResponse response = accountsApi.UpdateBrandWithHttpInfo(accountId, brandId, brand);
    string traceToken = response.Headers["X-Docusign-TraceToken"];

Note: Some API calls do not return an error, but instead provide error information inside the body of the HTTP response. In this case, you will need to have your code check the data returned from the API to make sure the call was successful.