水缸机器人

Appearance

错误处理 ​

概述 ​

Bngeuit 在调用 QQ Bot API 失败时会抛出 BotApiException，携带 HTTP 状态码、业务错误码和追踪 ID，便于排查问题。

异常捕获 ​

java
import cn.org.bukkit.bngeuit.Bngeuit;
import cn.org.bukkit.bngeuit.exception.BotApiException;

try {
    Bngeuit.sendGroupText(groupOpenid, 1, "Hello");
} catch (BotApiException e) {
    System.err.println("API 调用失败: " + e.getMessage());
    System.err.println("HTTP 状态码: " + e.getStatusCode());
    System.err.println("业务错误码: " + e.getErrCode());
    System.err.println("追踪ID: " + e.getTraceId());
}

BotApiException ​

方法返回类型说明
getMessage()String错误描述（含错误码中文释义）
getStatusCode()intHTTP 状态码（-1 表示非 HTTP 来源）
getErrCode()Integer业务错误码（来自响应 JSON 的 err_code）
getTraceId()String追踪 ID（来自响应 JSON 的 trace_id，联系腾讯排查时提供）

常见错误码 ​

消息发送 ​

错误码说明解决方案
40034100主动消息发送超过频控限制降低发送频率
40034105主动消息发送失败，无权限检查机器人权限
40034128被动回复时间或次数超限在 5 秒内回复，且只能回复一次
40034005回复消息 msg_id 已过期使用最新的消息 ID
40034006消息内容违规检查消息内容
40054005消息被去重使用不同的 msgSeq
40054007消息长度超限缩短消息内容

机器人状态 ​

错误码说明解决方案
40054002机器人被禁言等待禁言解除
40054003机器人不是群成员将机器人拉入群
40054016机器人已下线检查机器人状态
40054004无好友关系先添加好友

富媒体上传 ​

错误码说明解决方案
850019不支持的文件格式检查文件类型
850031上传文件超过大小限制压缩文件或分片上传
40093002超过今天发送文件容量上限等待次日重试
40034004富媒体信息转存失败重新上传

权限相关 ​

错误码说明解决方案
11253应用无接口访问权限检查应用权限配置
304036无 Markdown 模板权限申请模板权限
40062003无操作权限确认机器人角色

服务端错误 ​

错误码说明解决方案
50001服务内部错误稍后重试
50002频率限制降低请求频率
50055001消息发送异常稍后重试

最佳实践 ​

关键操作必须捕获异常 ​

java
@SubscribeEvent
public void onGroupAt(GroupAtMessageEvent e) {
    try {
        Bngeuit.replyGroupText(e.getGroupOpenid(), e.getId(), 1, "回复内容");
    } catch (BotApiException ex) {
        // 记录日志但不中断事件处理
        getLogger().warn("回复消息失败: {} (traceId={})", ex.getMessage(), ex.getTraceId());
    }
}

利用 TraceId 排查问题 ​

java
try {
    Bngeuit.sendGroupText(groupOpenid, 1, message);
} catch (BotApiException e) {
    if (e.getTraceId() != null) {
        // 记录 traceId 用于联系腾讯排查
        getLogger().error("API 失败，traceId: {}", e.getTraceId());
    }
}

频控场景的重试 ​

java
public void sendWithRetry(String groupOpenid, int msgSeq, String content, int maxRetries) {
    for (int i = 0; i < maxRetries; i++) {
        try {
            Bngeuit.sendGroupText(groupOpenid, msgSeq, content);
            return; // 成功
        } catch (BotApiException e) {
            if (e.getErrCode() != null && e.getErrCode() == 50002) {
                // 频率限制，等待后重试
                try { Thread.sleep(1000 * (i + 1)); } catch (InterruptedException ignored) {}
            } else {
                throw e; // 其他错误直接抛出
            }
        }
    }
}