错误处理
更新时间:2026-09-09
SDK 抛出的异常分为三类:
| 异常 | 触发时机 | 关键信息 |
|---|---|---|
IllegalArgumentException |
请求发送前的参数校验失败 | 异常消息指明缺失字段 |
BceClientException |
构建请求、网络连接、加密或响应解析等客户端错误 | 异常消息与 cause |
BceServiceException |
服务端返回错误响应 | errorCode、errorMessage、statusCode、requestId、errorType |
BceServiceException 继承 BceClientException,两者都是 RuntimeException,捕获时应先捕获 BceServiceException。
Java
1package com.example.kafka;
2
3import com.baidubce.BceClientException;
4import com.baidubce.BceServiceException;
5import com.baidubce.services.kafka.KafkaClient;
6import com.baidubce.services.kafka.model.cluster.GetClusterDetailRequest;
7import com.baidubce.services.kafka.model.cluster.GetClusterDetailResponse;
8
9public class ErrorHandlingDemo {
10
11 public static void main(String[] args) {
12 KafkaClient client = KafkaClientFactory.create();
13 try {
14 GetClusterDetailRequest request = new GetClusterDetailRequest();
15 request.setClusterId("{{集群 ID}}");
16
17 GetClusterDetailResponse response = client.getClusterDetail(request);
18 System.out.println("requestId=" + response.getMetadata().getBceRequestId());
19 System.out.println("state=" + response.getCluster().getState());
20 } catch (IllegalArgumentException e) {
21 // 参数校验失败,请求未发出,不需要重试
22 System.err.println("invalid request: " + e.getMessage());
23 } catch (BceServiceException e) {
24 // 服务端返回错误
25 System.err.printf("code=%s status=%d requestId=%s message=%s%n",
26 e.getErrorCode(), e.getStatusCode(),
27 e.getRequestId(), e.getErrorMessage());
28 } catch (BceClientException e) {
29 // 网络或客户端错误
30 System.err.println("client error: " + e.getMessage());
31 } finally {
32 client.shutdown();
33 }
34 }
35}
成功响应也可以获取请求标识,用于问题追踪:
Java
1String requestId = response.getMetadata().getBceRequestId();
BceServiceException.getErrorType() 返回 ErrorType.Client 或 ErrorType.Service,可用于判断是否值得重试:Service 类错误和 5xx 状态码可采用指数退避重试,Client 类错误重试无意义。
常见通用错误(定义于 com.baidubce.ErrorCode):
| 错误码 | 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 业务级错误码请参见错误返回。
评价此篇文章
