Object Storage Service (OSS) SDK for Python has three types of exceptions: ClientError, RequestError, and ServerError. These exceptions are defined in the oss2.exceptions submodule.

The following table describes the variable, type, and description of these exceptions.

  • If a ServerError exception occurs, an HTTP status code is returned for this variable.
  • If a ClientError or RequestError exception occurs, a fixed value is returned for this variable.
  • If a ServerError exception occurs, the OSS server returns the request ID for this variable.
  • If a ClientError or RequestError exception occurs, an empty string is returned for this variable.
Code and messagestrThe text in the Code and Message XML tags in an OSS error response. For more information, see Error responses.

Example of handling exceptions

The following code provides an example on how to handle an exception and display the HTTP status code of the error and the request ID when you attempt to download an object that does not exist:

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

# The AccessKey pair of an Alibaba Cloud account has permissions on all API operations. Using these credentials to perform operations in OSS is a high-risk operation. We recommend that you use a RAM user to call API operations or perform routine O&M. To create a RAM user, log on to the RAM console. 
auth = oss2.Auth('yourAccessKeyId', 'yourAccessKeySecret')
# Specify the endpoint of the region in which the bucket is located. For example, if the bucket is located in the China (Hangzhou) region, set the endpoint to https://oss-cn-hangzhou.aliyuncs.com. 
# Specify the name of the bucket. Example: examplebucket. 
bucket = oss2.Bucket(auth, 'https://oss-cn-hangzhou.aliyuncs.com', 'examplebucket')

    // Specify the name of the downloaded object. Example: exampleobject.txt. 
    stream = bucket.get_object('exampleobject.txt')
except oss2.exceptions.NoSuchKey as e:
    print('status={0}, request_id={1}'.format(e.status, e.request_id))            


ClientError occurs due to incorrect inputs on the client. For example, the error occurs when you use the bucket.batch_delete_objects method and receive an empty object list. The status value of ClientError is oss2.exceptions.OSS_CLIENT_ERROR_STATUS.


When an HTTP library error occurs, OSS SDK for Python converts the error to RequestError. The status value of RequestError is oss2.exceptions.OSS_REQUEST_ERROR_STATUS.


When the OSS server returns an HTTP status code, OSS SDK for Python converts the status code to ServerError. ServerError derives multiple subclasses based on the HTTP status code and OSS error code. The NotFound subclass corresponds to HTTP status code 404. The Conflict subclass corresponds to HTTP status code 409.

The following table describes common error codes.

Exception classHTTP status codeOSS error codeDescription
NotModified304NoneThe specified value of the If-Modified-Since parameter is later than the actual time when the object is modified.
InvalidArgument400InvalidArgumentThe request body is specified in a multipart upload request in which you set x-oss-complete-all to yes. In this case, the request body cannot be specified. Otherwise, an error occurs.
AccessDenied403AccessDeniedThe requester does not have relevant access permissions.
NoSuchBucket404NoSuchBucketThe specified bucket does not exist.
NoSuchKey404NoSuchKeyThe specified object does not exist.
NoSuchUpload404NoSuchUploadThe object is not completely uploaded in a multipart upload or resumable upload request.
NoSuchWebsite404NoSuchWebsiteConfigurationThe specified bucket does not have the static website hosting feature enabled.
NoSuchLifecycle404NoSuchLifecycleThe specified bucket has no lifecycle rules configured.
NoSuchCors404NoSuchCORSConfigurationThe specified bucket has no cross-origin resource sharing (CORS) rules configured.
BucketNotEmpty409BucketNotEmptyThe bucket to be deleted contains objects, parts generated by incomplete multipart upload tasks, or LiveChannels.
PositionNotEqualToLength409PositionNotEqualToLengthThe value of position in the request does not match the current object size.
ObjectNotAppendable409ObjectNotAppendableThe current object is not an appendable object.