帮你快速理解、总结文档立即下载

异常处理

最近更新时间:2026-10-21 18:34:03
我的收藏
本文档说明高性能桶 Python SDK 的错误处理方式。可按常见的客户端与服务端异常读取错误码、错误信息、请求 ID 及 HTTP 状态码,便于定位与处理问题。

错误类型

SDK 的异常定义在 qcloud_cos.cos_exception 中,调用方可根据异常类型区分错误来源:
异常类型
说明
CosClientError
客户端错误。如请求超时、网络异常,或 SDK 在本地校验失败(例如对高性能桶传入了不支持的参数、未启用 session 鉴权、Key 含非法路径段等)
CosServiceError
服务端错误。服务端返回了错误响应,可进一步读取错误码、错误信息与诊断 ID
CosServiceError 提供以下方法:
方法
描述
get_error_code()
获取错误码,如 NoSuchBucket、AccessDenied;服务端返回格式异常时返回 Unknown
get_error_msg()
获取错误的详细描述信息
get_status_code()
获取 HTTP 状态码
get_resource_location()
获取发生错误的资源
get_request_id()
获取本次请求的唯一标识,排查问题时可提供给技术支持
get_trace_id()
获取服务端调用链追踪 ID
get_origin_msg()
获取服务端返回的原始错误内容
get_digest_msg()
获取解析后的 dict 形式错误信息
HEAD 请求没有错误正文时,SDK 可能使用通用错误码,例如 404 对应 NoSuchResource。判断对象或桶是否不存在时,请使用 get_status_code() == 404。

示例

判断错误类型并提取错误码、错误信息、请求 ID 与 HTTP 状态码:
# -*- coding=utf-8 -*-
import os
from qcloud_cos import CosConfig, CosS3Client
from qcloud_cos.cos_exception import CosClientError, CosServiceError

# 高性能桶经 VPC 内网 HTTP 80 端口接入,SDK 的网关 DNS 负载均衡也仅对 HTTP 请求生效;SDK 默认 https,此处需显式指定 http。
config = CosConfig(
Scheme='http',
Region='ap-guangzhou',
SecretId=os.environ['COS_SECRET_ID'],
SecretKey=os.environ['COS_SECRET_KEY'],
Token=os.environ.get('COS_SECURITY_TOKEN'),
EnableRapidDomain=True)
client = CosS3Client(config)

try:
client.get_object(Bucket='examplebucket-x--1250000000', Key='not-exist-key')
except CosServiceError as e:
# 服务端错误,可读取错误码、错误信息与诊断 ID。
print('Code: %s' % e.get_error_code())
print('Message: %s' % e.get_error_msg())
print('StatusCode: %s' % e.get_status_code())
print('RequestId: %s' % e.get_request_id())
except CosClientError as e:
# 客户端错误,如超时、网络异常或本地参数校验失败。
print('Client error: %s' % e)

常见错误码

错误码
HTTP 状态码
说明
NoSuchBucket
404
请求的桶不存在
NoSuchKey
404
请求的对象不存在
NoSuchPolicy
404
桶未设置存储桶策略
NoSuchUpload
404
分块上传的 UploadId 不存在
AccessDenied
403
无权限访问,请检查 CAM 授权或桶策略
ExpiredToken
400
会话临时凭证已过期,需使用有效临时凭证重新发起请求
InvalidAccessKeyId
403
凭证不存在
BucketNotEmpty
409
删除桶时桶内仍有对象,需先清空对象
EntityTooSmall
400
除最后一块外的分块小于允许的最小值
InvalidPart
400
提交的分块信息无效,例如 ETag 与已上传分块不匹配
InvalidPartOrder
400
完成分块上传时 Parts 未按分块编号升序排列
错误码可结合 RequestId 一并用于问题排查。完整错误码列表请参见 错误码。