Docs

Torch Object Storage

Java

Exception Handling (Java SDK)

This document introduces exception handling when using the TOS SDK.

TOS Server-Side Error

The TOS server complies with HTTP specifications and defines detailed HTTP status codes and business error codes for scenarios involving request failures. For detailed information, please refer to TOS Server-side Status Codes and Error Codes Definition.

SDK Custom Exception

The TOS Java SDK defines two types of exceptions: TosClientException for client-side errors and TosServerException for server-side errors. Both exception classes inherit from TosException, which in turn extends RuntimeException.

Client-Side Exception: TosClientException

A TosClientException is typically thrown before the SDK sends a request to the TOS server. The following are scenarios in which this exception may be raised.

Parameter validation failed. For example, when the parameters of the XXInput class are empty or the bucket name is non-compliant (such as when the bucket name exceeds 63 characters), etc.

Transmission failures may occur during upload or download processes due to network anomalies, program interruptions, and other similar issues.

If a TosClientException occurs, it is recommended to first verify that the input parameters comply with the specifications. The TosClientException records the cause of the exception in its message, which can be obtained and analyzed using the TosClientException.getMessage() method.

Server-Side Exception: TosServerException

TosServerException is an exception parsed and thrown by the SDK based on the response returned from the TOS server, including information such as HTTP status codes and exception reasons. If a TosServerException occurs, refer to the definition of TOS server-side status codes and error codes to handle it.

Exception Handling Examples

For handling TosClientException and TosServerException thrown by the SDK, please refer to the Client General Example for details.

Last updated: 2025.09.19 20:00:28