本文档说明高性能桶 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 osfrom qcloud_cos import CosConfig, CosS3Clientfrom 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 未按分块编号升序排列 |