一、错误类型
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 未按分块编号升序排列 |
错误码可结合 RequestId 一并用于问题排查。完整错误码列表请参见 错误码。