错误处理
更新时间:2026-09-09
错误处理
Go SDK 通过 error 返回值报告错误,分为三类:
| 错误来源 | 类型 | 触发时机 | 关键信息 |
|---|---|---|---|
| 参数校验 | 标准库 error |
请求发送前的必填与取值校验失败 | 错误消息指明缺失字段 |
| 客户端错误 | *bce.BceClientError |
构建请求、网络连接、加密或响应解析失败 | Message |
| 服务端错误 | *bce.BceServiceError |
服务端返回错误响应 | Code、Message、RequestId、StatusCode |
BceServiceError 与 BceClientError 是相互独立的结构体,都实现 error 接口,彼此之间没有包含关系,因此必须分别断言,不能只判断其中一种:
Go
1package kafkademo
2
3import (
4 "fmt"
5 "log"
6
7 "github.com/baidubce/bce-sdk-go/bce"
8 "github.com/baidubce/bce-sdk-go/services/kafka"
9)
10
11func getClusterWithErrorHandling() {
12 client := newKafkaClient()
13
14 request := &kafka.GetClusterDetailRequest{
15 ClusterID: "{{集群 ID}}",
16 }
17
18 response, err := client.GetClusterDetail(request)
19 if err != nil {
20 switch typed := err.(type) {
21 case *bce.BceServiceError:
22 // 服务端返回错误
23 log.Printf("code=%s status=%d requestId=%s message=%s",
24 typed.Code, typed.StatusCode, typed.RequestId, typed.Message)
25 case *bce.BceClientError:
26 // 网络或客户端错误
27 log.Printf("client error: %s", typed.Message)
28 default:
29 // 参数校验失败,请求未发出,不需要重试
30 log.Printf("invalid request: %v", err)
31 }
32 return
33 }
34
35 if response.Cluster != nil {
36 fmt.Printf("state=%s
37", response.Cluster.State)
38 }
39}
成功响应不携带请求标识。 响应结构体不嵌入元数据字段,RequestId 只在 *bce.BceServiceError 上可读。排查成功请求时需要开启 SDK 日志。
判断是否值得重试:*bce.BceServiceError 且 StatusCode 为 5xx 时可采用指数退避重试;参数校验错误和 4xx 错误重试无意义。客户端默认已配置退避重试策略(最多 3 次),可通过 Retry 字段调整或用 bce.NewNoRetryPolicy() 关闭。
常见通用错误(bce 包中定义了同名常量,形如 bce.EACCESS_DENIED):
| 错误码 | HTTP 状态码 | 错误原因 | 处理建议 |
|---|---|---|---|
AccessDenied |
403 | 无权限访问目标资源 | 检查子用户权限策略与资源归属 |
InvalidAccessKeyId |
403 | AK 不存在或已禁用 | 确认 AK 有效,并检查是否误用其他账号凭证 |
SignatureDoesNotMatch |
400 | 签名不匹配 | 检查 SK 是否正确、有无多余空格 |
RequestExpired |
400 | 请求已过期 | 校准本机系统时间 |
MalformedJSON / InappropriateJSON |
400 | 请求体格式错误 | 检查请求结构体字段类型与必填项 |
InvalidURI |
404 | 路径或资源不存在 | 确认 Endpoint、ClusterID 等路径参数 |
PreconditionFailed |
412 | 资源状态不满足操作前置条件 | 先查询资源状态,待其进入可操作状态后重试 |
OptInRequired |
403 | 服务未开通 | 在控制台开通消息服务 for Kafka |
InternalError |
500 | 服务端内部错误 | 采用指数退避重试,持续失败请携带 RequestId 联系支持 |
Kafka 业务级错误码请参见错误返回。
评价此篇文章
