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

异常处理

最近更新时间:2026-10-21 18:34:05
我的收藏
本文档说明高性能桶 Go SDK 的错误处理方式。当 SDK 调用失败时,会返回统一的错误类型 *cos.ErrorResponse,可从中获取错误码、错误信息、请求 ID 及 HTTP 状态码,便于定位与处理问题。

错误类型

SDK 调用失败时返回的错误可断言为 *cos.ErrorResponse,其结构如下:
字段
类型
描述
Code
string
错误码,如 NoSuchBucket、AccessDenied
Message
string
错误的详细描述信息
Resource
string
发生错误的资源
RequestID
string
本次请求的唯一标识,排查问题时可提供给技术支持
TraceID
string
服务端调用链追踪 ID
Response
*http.Response
原始 HTTP 响应,可通过 Response.StatusCode 获取 HTTP 状态码

辅助函数

SDK 提供以下辅助函数便于判断与提取错误:
函数
描述
func IsNotFoundError(e error) bool
判断错误是否为资源不存在(HTTP 404),如对象或桶不存在
func IsCOSError(e error) (*ErrorResponse, bool)
类型断言,若为 COS 错误则取出 *ErrorResponse 并返回 true

示例

判断错误并提取错误码、错误信息、请求 ID 与 HTTP 状态码:
package main

import (
"context"
"log"
"net/http"
"net/url"
"os"
"time"

"github.com/tencentyun/cos-go-sdk-v5"
)

func main() {
u, _ := url.Parse("https://examplebucket-x--1250000000.cosrapid.ap-guangzhou.myqcloud.com")
b := &cos.BaseURL{BucketURL: u}
base := &cos.AuthorizationTransport{
SecretID: os.Getenv("SECRETID"),
SecretKey: os.Getenv("SECRETKEY"),
}
c := cos.NewClient(b, &http.Client{
Transport: cos.NewRapidCredentialTransport(base),
Timeout: 30 * time.Second,
})

ctx := context.Background()
_, err := c.Object.Get(ctx, "not-exist-key", nil)
if err != nil {
// 使用 IsNotFoundError 判断对象/桶是否不存在。
if cos.IsNotFoundError(err) {
log.Println("object not found")
return
}
// 取出 *ErrorResponse,读取详细字段。
if e, ok := cos.IsCOSError(err); ok {
log.Printf("Code: %s", e.Code)
log.Printf("Message: %s", e.Message)
log.Printf("RequestID: %s", e.RequestID)
if e.Response != nil {
log.Printf("StatusCode: %d", e.Response.StatusCode)
}
return
}
// 其他错误(如网络错误)。
log.Fatalf("request failed: %v", err)
}
}

常见错误码

错误码
HTTP 状态码
说明
NoSuchBucket
404
请求的桶不存在
NoSuchKey
404
请求的对象不存在
NoSuchPolicy
404
桶未设置存储桶策略
AccessDenied
403
无权限访问,请检查 CAM 授权或桶策略
BucketNotEmpty
409
删除桶时桶内仍有对象,需先清空对象
错误码可结合 RequestID 一并用于问题排查。