水缸机器人

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, "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应用无接口访问权限检查应用权限配置（群成员、黑名单等内邀接口未开通时即报此码）
40062003无操作权限确认机器人角色

模板 Markdown 权限码

旧文档中的 304036（无 Markdown 模板权限）对应模板 Markdown 能力，该能力已随官方废弃从框架移除（MessageMarkdown 只保留 content 与 forceVerifyImageResource），不再需要申请。

图片素材 ​

错误码说明解决方案
40035001图片格式不支持扩展名与 Content-Type 需为 png/jpeg/gif/webp 且一致
40035002图片超过大小上限单张不超过 10MB
40035003上传任务不存在或已过期上传任务 4 小时有效；complete 的 md5 必须是直传返回的 ETag
40035006素材服务内部错误稍后重试
40035007图片数量超过上限单机器人上限 100 张，删除部分素材后重试
40035008图片不存在或已被删除检查 image_id
40035009图片已过期或被删除引用链接失效，重新上传
40035010引用链接无效或不属于当前机器人确认链接来源与 AppID

服务端错误 ​

错误码说明解决方案
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, message);
} catch (BotApiException e) {
    if (e.getTraceId() != null) {
        // 记录 traceId 用于联系腾讯排查
        getLogger().error("API 失败，traceId: {}", e.getTraceId());
    }
}

频控场景的重试 ​

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