OSS SDK for Java exceptions are classified into two types: OSSException and ClientException. Both are subclasses of RuntimeException.

Example of handling exceptions

The following code provides an example on how to handle exceptions:

try {
    // Perform operations on OSS such as object upload.
    ossClient.putObject(...);
} catch (OSSException oe) {
    System.out.println("Caught an OSSException, which means your request made it to OSS, "
            + "but was rejected with an error response for some reason.");
    System.out.println("Error Message: " + oe.getErrorMessage());
    System.out.println("Error Code:       " + oe.getErrorCode());
    System.out.println("Request ID:      " + oe.getRequestId());
    System.out.println("Host ID:           " + oe.getHostId());
} catch (ClientException ce) {
    System.out.println("Caught an ClientException, which means the client encountered "
            + "a serious internal problem while trying to communicate with OSS, "
            + "such as not being able to access the network.");
    System.out.println("Error Message: " + ce.getMessage());
} finally {
    if (ossClient != null) {
        ossClient.shutdown();
    }
}
            

ClientException

A ClientException indicates an exception that occurs when a client sends a request or transmit data to OSS. For example, a ClientException is returned when a request is sent under poor network conditions. A ClientException is also returned when an I/O exception occurs during object upload.

OSSException

OTSException: indicates a server exception that arises from the resolution of a server error message. A ServiceException includes the error code and message returned by OSS so that you can identify and resolve the error.

OSSException involves the following error information:

ParameterDescription
CodeThe error code returned by OSS.
MessageThe detailed error message returned by OSS.
RequestIdThe UUID used to uniquely identify the request. If the problem persists, you can provide the request ID of a problem to the OSS development engineers for help.
HostIdThe ID of the host in the accessed OSS cluster, which is the same as the host ID specified in the request.

Common OSS error codes

Error codeDescriptionHTTP status code
AccessDeniedThe error message returned because access is denied.403
BucketAlreadyExistsThe error message returned when the bucket already exists.409
BucketNotEmptyThe error message returned when the bucket is not empty.409
EntityTooLargeThe error message returned because the entity is too large.400
EntityTooSmallThe error message returned because the entity is too small.400
FileGroupTooLargeThe error message returned because the object group is too large.400
FilePartNotExistThe error message returned when the part does not exist.400
FilePartStaleThe error message returned when the part is expired.400
InvalidArgumentThe error message returned when the parameter format is invalid.400
InvalidAccessKeyIdThe error message returned because AccessKey ID does not exist.403
InvalidBucketNameThe error message returned when the bucket name is invalid.400
InvalidDigestThe error message returned when the digest is invalid.400
InvalidObjectNameThe error message returned when the object name is invalid.400
InvalidPartThe error message returned when the part is invalid.400
InvalidPartOrderThe error message returned when the part order is invalid.400
InvalidTargetBucketForLoggingThe error message returned because the target bucket specified for logging is invalid.400
InternalErrorThe error message returned when an internal OSS error occurs.500
MalformedXMLThe error message returned when the XML format is invalid.400
MethodNotAllowedThe error message returned when the method is not supported.405
MissingArgumentThe error message returned when a parameter is missing.411
MissingContentLengthThe error message returned when the content length is missing.411
NoSuchBucketThe error message returned when no such bucket exists.404
NoSuchKeyThe error message returned because no such object exists.404
NoSuchUploadThe error message returned when no such multipart upload ID exists.404
NotImplementedThe error message returned when the method cannot be implemented.501
PreconditionFailedThe error message returned when a precondition error occurs.412
RequestTimeTooSkewedThe error message returned when the time deviation of the OSS client and OSS server exceeds 15 minutes.403
RequestTimeoutThe error message returned because the request has timed out.400
SignatureDoesNotMatchThe error message returned when a signature error occurs.403
InvalidEncryptionAlgorithmErrorThe error message returned because the specified encryption algorithm based on entropy encoding is invalid.400