异常处理

最近更新时间:2026-04-10 18:12:02

我的收藏

简介

本文档介绍 COS Go SDK 向量存储桶服务中的错误处理机制。向量服务接口返回的错误与标准 COS XML 错误格式不同,采用 JSON 格式响应,错误码通过 HTTP 响应头 X-Cos-Error-Code 返回。Go SDK 将这些错误封装为 *cos.VectorErrorResponse 结构体,方便开发者进行统一的错误处理。

错误处理机制

向量服务的所有 API 方法在调用失败时,都会返回一个非 nilerror。可以借助 SDK 的辅助函数 cos.IsVectorError() 来进行错误判断和处理。方法原型如下:
func IsVectorError(e error) (*VectorErrorResponse, bool)
辅助函数判断错误是否为向量服务返回的业务错误。如果是,则返回 *VectorErrorResponse 对象和 true;否则返回 nilfalse
VectorErrorResponse 结构体
字段
类型
描述
Code
string
错误码,来自 HTTP 响应头 X-Cos-Error-Code
Message
string
具体的错误信息描述
FieldList
[]VectorValidateField
参数校验失败详情列表(仅在参数校验失败时返回)
RequestID
string
标识该次请求的唯一 ID,排查问题时需要提供
Response
*http.Response
发生错误时的原始 HTTP 响应对象
VectorValidateField 结构体
字段
类型
描述
Message
string
参数校验失败的原因
Path
string
发生校验错误的参数字段路径

处理代码示例

以下示例展示了如何从 error 转换为 *cos.VectorErrorResponse 并获取详细错误信息:

使用 cos.IsVectorError() 辅助函数(推荐)


package main

import (
"context"
"fmt"
"net/http"
"os"

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

func main() {
vectorURL, _ := cos.NewVectorURL("ap-guangzhou", true)
client := cos.NewClient(&cos.BaseURL{VectorURL: vectorURL}, &http.Client{
Transport: &cos.AuthorizationTransport{
SecretID: os.Getenv("COS_VECTORS_SECRET_ID"),
SecretKey: os.Getenv("COS_VECTORS_SECRET_KEY"),
},
})

opt := &cos.CreateVectorBucketOptions{
VectorBucketName: "examplebucket-1250000000",
}

res, _, err := client.Vector.CreateVectorBucket(context.Background(), opt)
if err != nil {
if vecErr, ok := cos.IsVectorError(err); ok {
// 向量服务业务错误,可以根据错误码进行针对性处理
switch vecErr.Code {
case "ConflictException":
fmt.Println("向量桶已存在,无需重复创建")
case "ValidationException":
fmt.Printf("参数校验失败: %s\\n", vecErr.Message)
for _, f := range vecErr.FieldList {
fmt.Printf(" 字段 %s: %s\\n", f.Path, f.Message)
}
case "ServiceQuotaExceededException":
fmt.Println("已超出服务配额限制,请联系客服提升配额")
case "AccessDeniedException":
fmt.Println("访问被拒绝,请检查密钥权限配置")
default:
fmt.Printf("向量服务错误 [%s]: %s (RequestID: %s)\\n",
vecErr.Code, vecErr.Message, vecErr.RequestID)
}
} else {
// 非业务错误(网络故障、DNS 解析失败、超时等)
fmt.Printf("请求失败: %v\\n", err)
}
return
}

fmt.Printf("向量桶创建成功,QCS: %s\\n", res.VectorBucketQcs)
}

使用 Go 标准类型断言

您也可以使用 Go 标准的类型断言来判断错误类型,并获取详细的错误信息。
res, resp, err := client.Vector.CreateIndex(context.Background(), opt)
if err != nil {
if vecErr, ok := err.(*cos.VectorErrorResponse); ok {
fmt.Printf("错误码: %s, 错误信息: %s, 请求ID: %s\\n",
vecErr.Code, vecErr.Message, vecErr.RequestID)
} else {
fmt.Printf("请求失败: %v\\n", err)
}
return
}
如果 error 能成功转换为*cos.VectorErrorResponse,您能够通过*cos.VectorErrorResponse.Code字段获取到向量桶服务端返回的具体的错误码信息。

服务端错误码

以下是向量存储桶服务可能返回的所有错误码:
错误码
HTTP 状态码
描述
ValidationException
400
请求参数不合法,例如缺少必填字段、字段格式错误或数值超出范围。此时 FieldList 中会包含具体的校验失败详情
KmsDisabledException
400
KMS 服务不可用
KmsInvalidKeyUsageException
400
指定的 KMS Key 用途不兼容
KmsInvalidStateException
400
指定的 KMS Key 状态不合法
KmsNotFoundException
400
指定的 KMS Key 不存在
ServiceQuotaExceededException
402
请求超过服务配额限制,例如向量桶或索引数量达到上限
AccessDeniedException
403
访问被拒绝,请检查密钥权限或资源策略配置
NotFoundException
404
请求的资源不存在,例如指定的向量桶或索引未找到
ConflictException
409
资源冲突,例如尝试创建已存在的向量桶或索引
TooManyRequestsException
429
请求频率过高,已超出限流阈值,请降低请求速率后重试
InternalServerException
500
服务内部错误,请稍后重试
ServiceUnavailableException
503
服务暂时不可用,请稍后重试
详细的服务端异常处理和错误码介绍还可参见 错误码 文档。