> You are reading the Docusign Developer Documentation. For clean Markdown of any page, append .md to the page URL. > > Documentation indexes by section: > - APIs and SDKs: https://docusign.docs.buildwithfern.com/docs/llms.txt > - Platform 101: https://docusign.docs.buildwithfern.com/platform/llms.txt > - Extension Apps: https://docusign.docs.buildwithfern.com/extension-apps/llms.txt > - Docusign CLI: https://docusign.docs.buildwithfern.com/docusign-cli/llms.txt > > Authentication (OAuth, JWT Grant, M2M): https://docusign.docs.buildwithfern.com/platform/auth > Webhooks and Connect: https://docusign.docs.buildwithfern.com/platform/webhooks > > OpenAPI specifications: https://docusign.docs.buildwithfern.com/openapi.json > MCP server: https://docusign.docs.buildwithfern.com/_mcp/server # Java SDK: Calling methods and handling errors ## Java SDK: Calling methods and handling errors > **Note** > > Learn about [Quickstart](/docs/esign-rest-api/quickstart) and how you can use it to quickly set up and run eSignature REST API code examples. ## Calling methods Making API calls through the [Java SDK](/docs/esign-rest-api/sdks/java) requires calling defined methods in classes in the `com.docusign.esign` namespaces. Each of these classes corresponds to a group of endpoints that are used for specific feature areas related to the eSignature REST API. For any eSignature REST API resource, you may perform: * Two methods at the resource data set level: GET and POST methods on a given resource. These raw API calls correspond to equivalent `list` and `create` API Reference methods, i.e. Java SDK methods `listBrands` and `createBrand`. * Three methods at a specific resource data set row (a single record): GET, PUT, and DELETE methods on a single record. These raw API calls correspond to equivalent `get`, `update`, and `delete` API object methods, i.e. Java SDK methods `getBrand`, `updateBrand`, and `deleteBrand`. Note that resource data set row operations require a specific resource identifier such as a `brandId` GUID. Within the context of the Java SDK, each specific REST endpoint contains different methods that can be used to modify the underlying object models. As an example, here are four methods that can be used to interact with the `AccountsApi Brand` object: ```text AccountsApi.createBrand(accountId, brand); AccountsApi.getBrand(accountId, brandId); AccountsApi.updateBrand(accountId, brandId, brand); AccountsApi.deleteBrand(accountId, brandId); ``` The return type for the object will change. In the example above, all return types for these methods, with the exception of `deleteBrand`, use the `Brand` object type. When working with similar methods such as `listBrands`, though the underlying individual components are similar or even identical, the return type is different. Methods also contain nested classes that control the various API list options (“arrays” in other programming languages) for the various features of the eSignature API. These nested classes contain their own subsequent getter/setter methods to control their intended features, often for option groups. Here is how you would retrieve the previously applied brand options on a specific brand: ```text GetBrandOptions().setIncludeLogos(includeLogos); GetBrandOptions().setIncludeExternalReferences(includeExternalReferences); ``` Finally, methods can have operator overloading (different functions with the same name but different parameters) capabilities. These different methods are used by the Docusign Java SDK client to generate the underlying JSON used by the eSignature REST API. ## Handling errors Error handling is an important part of developing your software. Your code should handle both expected and unexpected errors. The Java 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 `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](/docs/esign-rest-api/esign101/error-codes) 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 Java 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 `RequestJWTUserToken` method for obtaining an OAuth token using JWT is included in the SDK, an `ApiException` is thrown if the RSA key or `UserId` is missing or malformed. [Troubleshooting for common errors](/docs/esign-rest-api/esign101/error-codes/troubleshooting-common-errors) has detailed information about causes and resolutions for specific errors. ## Obtaining the TraceToken for solving problems via Support Every API response includes a GUID that can be used to trace it on the back end by Docusign employees, including [Support](https://support.docusign.com/). 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. To obtain the trace token, you will first need to call the `getResponseHeaders` method provided by the `ApiException` class. Here is an example of how to obtain the trace token: ```text try { // failing code } catch (ApiException e) { System.out.println("Docusign Exception: " + e.getResponseHeaders().get("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 ensure the call was successful.