简介
本文档介绍 COS Go SDK 向量存储桶服务中的错误处理机制。向量服务接口返回的错误与标准 COS XML 错误格式不同,采用 JSON 格式响应,错误码通过 HTTP 响应头
X-Cos-Error-Code 返回。Go SDK 将这些错误封装为 *cos.VectorErrorResponse 结构体,方便开发者进行统一的错误处理。错误处理机制
向量服务的所有 API 方法在调用失败时,都会返回一个非
nil 的 error。可以借助 SDK 的辅助函数 cos.IsVectorError() 来进行错误判断和处理。方法原型如下:func IsVectorError(e error) (*VectorErrorResponse, bool)
辅助函数判断错误是否为向量服务返回的业务错误。如果是,则返回
*VectorErrorResponse 对象和 true;否则返回 nil 和 false。 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 mainimport ("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 | 服务暂时不可用,请稍后重试 |