OSS Python SDK has three types of exceptions: ClientError, RequestError, and ServerError, which are defined in the oss2.exceptions sub-module.

The following table lists the member variables of exceptions.

Variable Type Description
status int
  • ServerError: HTTP status code
  • ClientError and RequestError: fixed values
request_id str
  • ServerError: request ID returned by the OSS server
  • ClientError and RequestError: empty string
Code and message str Correspond to text text in the Code and Message XML Tags in OSS error response.

Example for handling exceptions

The following code demonstrates how to handle exceptions when downloading an object that does not exist, and how to print the HTTP status code and request ID of the error messages.

# -*- coding: utf-8 -*-
import oss2

# It is highly risky to log on with AccessKey of an Alibaba Cloud account because the account has permissions on all the APIs in OSS. We recommend that you log on as a RAM user to access APIs or perform routine operations and maintenance. To create a RAM account, log on to https://ram.console.aliyun.com.
auth = oss2.Auth('<yourAccessKeyId>', '<yourAccessKeySecret>')
# This example uses endpoint China East 1 (Hangzhou). Specify the actual endpoint based on your requirements.
bucket = oss2.Bucket(auth, 'http://oss-cn-hangzhou.aliyuncs.com', '<yourBucketName>')

    stream = bucket.get_object('random-key.txt')
except oss2.exceptions.NoSuchKey as e:
    print('status={0}, request_id={1}'.format(e.status, e.request_id))


ClientError is caused by input error on the client side. For example, a ClientError is thrown when an empty object name list is received when the bucket.batch_delete_objects method is used. The status value of ClientError objects is oss2.exceptions.OSS_CLIENT_ERROR_STATUS.


When an exception is thrown by the underlying HTTP library, the Python SDK will convert the exception to RequestError. The status value of ClientError objects is fixed to oss2.exceptions.OSS_CLIENT_ERROR_STATUS.


When an HTTP error code is returned by the OSS server, Python SDK converts it into a ServerError. ServerError is divided into multiple subclasses based on the HTTP status code and OSS error code. The NotFound subclass corrresponds to all 404 exceptions, and the Conflict subclass corresponds to all 409 exceptions.

The following table lists common error codes.

Exception class HTTP status code OSS error code Description
NotModified 304 Null It is not modified.
AccessDenied 403 AccessDenied The access is denied.
NoSuchBucket 404 NoSuchBucket The bucket does not exist.
NoSuchKey 404 NoSuchKey The file does not exist.
NoSuchUpload 404 NoSuchUpload The multipart upload does not exist.
NoSuchWebsite 404 NoSuchWebsiteConfiguration The static website hosting is not configured.
NoSuchLifecycle 404 NoSuchLifecycle The lifecycle management is not configured.
NoSuchCors 404 NoSuchCORSConfiguration CORS is not configured.
BucketNotEmpty 409 BucketNotEmpty The bucket is not empty.
PositionNotEqualToLength 409 PositionNotEqualToLength The Append position is not equal to the object length.
ObjectNotAppendable 409 ObjectNotAppendable The object is not appendable.