edit-icon download-icon

Exception handling

Last Updated: Oct 23, 2017

If an exception is thrown when you call an OSSClient-class interface, the operation fails. Otherwise, the operation is successful. When an exception is thrown, the data returned by the method is invalid.

The two types of OSS Java SDK exceptions are: OSSException at the server side and ClientException at the client side, both are inherited from RuntimeException.

Exception handling example

  1. try {
  2. // Do some operations with the instance here, such as put object...
  3. client.putObject(...);
  4. } catch (OSSException oe) {
  5. System.out.println("Caught an OSSException, which means your request made it to OSS, "
  6. + "but was rejected with an error response for some reason.");
  7. System.out.println("Error Message: " + oe.getErrorCode());
  8. System.out.println("Error Code: " + oe.getErrorCode());
  9. System.out.println("Request ID: " + oe.getRequestId());
  10. System.out.println("Host ID: " + oe.getHostId());
  11. } catch (ClientException ce) {
  12. System.out.println("Caught an ClientException, which means the client encountered "
  13. + "a serious internal problem while trying to communicate with OSS, "
  14. + "such as not being able to access the network.");
  15. System.out.println("Error Message: " + ce.getMessage());
  16. } finally {
  17. if (client != null) {
  18. client.shutdown();
  19. }
  20. }


ClientException occurs when a client attempts to send a request or transmits data to OSS. The ClientException is thrown, for example, when network connectivity is unavailable during request transfer, or I/O exception occurs during object upload.


OSSException indicates a server error, which is from parsing a server error message. The OSS returns the error code and error message. This helps to locate the problem and handle it properly.

OSSException generally contains the following error information:

  • Code: The error code OSS returns to users.

  • Message: The detailed error message provided by OSS.

  • RequestId: The UUID that uniquely identifies the request. When you cannot solve the problem, you can seek help from OSS development engineers by providing the RequestId.

  • HostId: The accessed OSS cluster, which is consistent with the Host ID carried in the user request.

Common OSS error codes

Error code Description HTTP status code
AccessDenied The access is denied. 403
BucketAlreadyExists The bucket already exists. 409
BucketNotEmpty The bucket is not empty. 409
EntityTooLarge The entity is too large. 400
EntityTooSmall The entity is too small. 400
FileGroupTooLarge The object group is too large. 400
FilePartNotExist The object part does not exist. 400
FilePartStale The object part has expired. 400
InvalidArgument The parameter format is invalid. 400
InvalidAccessKeyId The AccessKeyID does not exist. 403
InvalidBucketName The bucket name is invalid. 400
InvalidDigest The digest is invalid. 400
InvalidObjectName The object name is invalid. 400
InvalidPart The part is invalid. 400
InvalidPartOrder The part order is invalid. 400
InvalidTargetBucketForLogging An invalid target bucket exists in the logging operation. 400
InternalError An error occurs in OSS. 500
MalformedXML The XML format is invalid. 400
MethodNotAllowed The method is not supported. 405
MissingArgument A parameter is missing. 411
MissingContentLength The content length is missing. 411
NoSuchBucket The bucket does not exist. 404
NoSuchKey The object does not exist. 404
NoSuchUpload The multipart upload ID does not exist. 404
NotImplemented The method cannot be processed. 501
PreconditionFailed Preconditioning fails. 412
RequestTimeTooSkewed The request initiation time exceeds the server time by 15 minutes. 403
RequestTimeout The request times out. 400
SignatureDoesNotMatch The signature is incorrect. 403
InvalidEncryptionAlgorithmError The specified entropy encryption algorithm is incorrect. 400
Thank you! We've received your feedback.