Calling Python SDK methods and handling errors

Calling methods

Making API calls through the Python SDK requires calling defined methods in classes in the docusign_esign namespaces. Each of these classes correspond to a group of endpoints that are used for specific feature areas related to the eSignature REST API.

Each specific REST endpoint typically has two different methods that can be used to call it. As an example, here are the two methods that can be used to make a call to update a brand:

    accounts_api.update_brand(account_id, brand_id, **kwargs)
    accounts_api.update_brand_with_http_info(account_id, brand_id, **kwargs)

The difference between update_brand and update_brand_with_http_info is that the update_brand method returns only the JSON object that is being sent back from the API. On the other hand, the update_brand_with_http_info method provides both 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 header_params 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.

By default, both of these methods make a synchronous HTTP request. You can make an asynchronous request by defining a callback function and passing that function to the method as part of the kwargs.

Handling errors

As with all Python code, error handling is an important part of developing your software. Your code should handle both expected and unexpected errors.

The Python 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 error_message objects, which contain useful information that can help you 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 as a result of issues with authentication.
• Issues in deserialization of the response JSON. If the JSON sent back by the API cannot be properly deserialized into the Python objects that the SDK is expecting, an ApiException is thrown, and the “bad” JSON is returned in the Message property of the exception.
• JWT issues with either the private RSA key pair or UserId. Since the request_jwt_user_token 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 TraceToken for solving problems via Customer Support

Every API response includes a GUID that can be used to trace it on the back end by Docusign employees, including Customer Support. This GUID is called the TraceToken. The TraceToken enables Customer 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.

To obtain the TraceToken, you will first need to call the with_http_info variant of the method so that you retain the header of the response.

    response = accounts_api.update_brand_with_http_info(account_id, brand_id)

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 ensure the call was successful.