edit-icon download-icon

Exception handling

Last Updated: Oct 24, 2017

If an error occurs during the runtime of a project, the Python SDK throws an exception accordingly.

The three types of exceptions are ClientError, RequestError, and ServerError. They are all subclasses of OssError, and are defined in the oss2.exceptions submodule.

OssError has the following important member variables:

  • status: int type. It is an HTTP status code for ServerError or a fixed value for the other two types of exceptions.

  • request_id: str type. It is the request ID returned by the OSS server for ServerError or a null string for the other two types of exceptions.

  • code and message: str type. It is the texts in the two XML tags of Code and Message in OSS error response format.


ClientError is caused by input error on the client side. For example, ClientError is thrown when an empty object name list is received during Bucket.batch_delete_objects. The status value of ClientError objects is fixed to oss2.exceptions.OSS_CLIENT_ERROR_STATUS.


When an exception is thrown by the underlying HTTP library, the Python SDK converts the exception to RequestError. The status value of such exceptions is fixed to oss2.exceptions.OSS_REQUEST_ERROR_STATUS.


When the OSS server returns an HTTP error code of 4xx or 5xx, the Python SDK converts the response of the OSS server to ServerError.

The following subclasses are derived from status and code to make the usage of Python SDK easy:

Exception class Corresponding 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 name 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.

Besides, all exceptions of the 404 status code are subclasses of NotFound, and all exceptions of the 409 status code are subclasses of Conflict.

Note: Not all OSS error codes have corresponding exceptions. Currently, only common exceptions are defined.


The following code handles the exception when the object name does not exist during object download, and prints the HTTP status code and the request ID:

  1. # -*- coding: utf-8 -*-
  2. import oss2
  3. auth = oss2.Auth ('Your AccessKeyID', 'Your AccessKeySecret')
  4. bucket = oss2.Bucket (auth, 'Your endpoint', 'your bucket name')
  5. try:
  6. stream = bucket.get_object('random-key.txt')
  7. except oss2.exceptions.NoSuchKey as e:
  8. print('status={0}, request_id={1}'.format(e.status, e.request_id))
Thank you! We've received your feedback.