# API 使用限制 (/zh-CN/realtime-media/rtm/reference/usage-limits-and-errors/api-limits/flutter) > For AI agents: see the complete documentation index at [llms.txt](/llms.txt). 本文适用于 RTM 2.x 客户端 SDK 和 RESTful API,介绍各层级的使用限制、超出限制后的行为,以及容量规划时的估算方法。 :::note[微信小程序适用范围] 微信小程序支持 Message Channel 和 User Channel,以及 Presence、Storage、Lock 和 Token 等已支持能力。本文中所有与 Stream Channel 和 Topic 相关的配额、消息规格、示例及调优建议对微信小程序均不适用;其余限制请按小程序已支持的功能使用。 ::: ## 快速导航 [#快速导航] | 使用场景 | 参考章节 | | --- | --- | | 调用返回了限频错误 | [调用频率限制](#41-调用频率限制) | | 发送失败,提示消息过长或参数超限 | [消息规格](#43-消息规格) | | 频道人数增加后延迟上升、用户反复重连 | [频道消息速率建议值](#32-频道消息速率建议值)、[场景示例](#6-场景示例怎么对照-32-做规划) | | 上线前估算容量 | [PCU 估算](#21-怎么估算你的-pcu)、[频道消息速率建议值](#32-频道消息速率建议值)、[场景示例](#6-场景示例怎么对照-32-做规划) | | 想申请提高某个上限 | [申请提升与提前沟通](#9-申请提升与提前沟通) | ### 限制层级 [#限制层级] RTM 的限制分为四层。上层限制约束总量,下层限制约束单个对象;同一次调用可能同时受到多层限制。 | 层级 | 作用对象 | 超出后怎么发现 | 章节 | | --- | --- | --- | --- | | 账号级 | 你的声网账号 | RESTful API 返回配额错误 | [第 1 章](#1-账号级限制) | | 项目级(App ID) | 单个项目 | 多数为建议值,超出前需联系技术支持 | [第 2 章](#2-项目级限制app-id) | | 频道级 | 单个频道 | 容量类返回错误;速率类为建议值 | [第 3 章](#3-频道级限制) | | 客户端级 | 单个 RTM 客户端实例 | SDK 错误回调 | [第 4 章](#4-客户端级限制) | ### 限制类型 [#限制类型] | 类型 | 含义 | 超出后 | 可否调整 | | --- | --- | --- | --- | | 固定上限 | 系统硬性约束 | 调用失败并返回错误 | 否 | | 默认上限 | 默认配额 | 调用失败并返回错误 | 可申请提升,见[第 9 章](#9-申请提升与提前沟通) | | 建议值 | 在此范围内可获得最佳性能 | 通常不报错 | 建议超出前联系技术支持 | | 不限数量 | 资源数量不设上限 | — | 不代表容量无限,仍受速率和吞吐约束 | ## 1. 账号级限制 [#1-账号级限制] | 限制项 | 数值 | 类型 | 说明 | | --- | --- | --- | --- | | RESTful API 总调用速率 / 账号 | 1000 次/秒 | 默认上限 | 账号下所有项目、所有 RESTful API 合计;超出返回 HTTP 429。 | ## 2. 项目级限制(App ID) [#2-项目级限制app-id] | 限制项 | 数值 | 类型 | 说明 | | --- | --- | --- | --- | | 峰值同时在线用户数(PCU) | 20 万 | 建议值 | 预计超过时请提前联系技术支持。估算方法见[2.1](#21-怎么估算你的-pcu)。 | | 总上行消息速率 | 10 万条/秒 | 建议值 | 项目下所有客户端和 RESTful API 发送量合计。 | | Message Channel 数量 | 不限数量 | 不限数量 | 频道随用随取,无需预先创建。 | | Stream Channel 数量 | 不限数量 | 不限数量 | 频道随用随取,无需预先创建。 | | Channel Metadata 总量 | 100 万 | 建议值 | 预计超过时请提前联系技术支持。 | | User Metadata 总量 | 100 万 | 建议值 | 预计超过时请提前联系技术支持。 | | Lock 总量 | 100 万 | 建议值 | 预计超过时请提前联系技术支持。 | | 历史消息存储时长 | 1、7、30、90、365 天或永久 | 默认上限 | 在控制台按项目配置。已写入消息的保存时长不受后续配置影响。 | ### 2.1 怎么估算你的 PCU [#21-怎么估算你的-pcu] RTM 的限制和计费都以 PCU 为单位,而业务指标通常只有 DAU、房间数或课堂数。按业务形态选择对应的估算方法: | 业务形态 | 你已有的数据 | PCU 估算公式 | | --- | --- | --- | | IM / 社交 | DAU、用户日均在线时长 | PCU ≈ DAU × 日均在线时长 ÷ 24 小时 × 峰值系数 | | 直播 / 秀场 | 同时开播房间数、单房间平均观众数 | PCU ≈ 同时开播房间数 × 单房间平均观众数 × 峰值系数 | | 教育 / 会议 | 同一时段的课堂数、每场人数 | PCU ≈ 同一时段课堂数 × 每场人数 | | 游戏 | 同时在线玩家数(CCU) | PCU ≈ CCU | 峰值系数用于把日均值放大到峰值时段,经验上取 2–3。有明确活动峰值的业务(例如大促、赛事、开学)请直接按活动峰值估算,不要使用日均值。 常见的估算偏差包括: - 多端登录按多个连接计。同一用户同时在手机和网页登录时,PCU 计 2。 - `heartbeatInterval` 会影响 PCU。心跳间隔越长,掉线用户被判定离线越慢,统计出的 PCU 越偏高。默认值为 5 秒,范围为 5–1800 秒。 ## 3. 频道级限制 [#3-频道级限制] ### 3.1 容量 [#31-容量] | 限制项 | 数值 | 类型 | 说明 | | --- | --- | --- | --- | | Message Channel 订阅者数(未开启 Presence) | 不限数量 | 不限数量 | 仍受[3.2 的消息速率建议值](#32-频道消息速率建议值)约束。 | | Message Channel 订阅者数(开启 Presence) | 5000 人 | 建议值 | 预计超过时请提前联系技术支持。 | | Message Channel 发布者数 | 不限数量 | 不限数量 | — | | Stream Channel 在线用户数 | 128 人 | 固定上限 | 第 129 人 `join` 失败并返回错误码。需要更大规模时使用多个 Stream Channel 或改用 Message Channel。 | | Stream Channel 内 Topic 数 | 不限数量 | 不限数量 | Topic 随首个发布者加入创建,最后一个发布者离开后销毁。 | | 频道内锁数量 | 32 把 | 建议值 | 预计超过时请提前联系技术支持。 | :::note 小程序不支持 Stream Channel,因此不适用上表中的 Stream Channel 在线用户数和 Topic 数限制;其他 Message Channel 和锁限制适用。 ::: ### 3.2 频道消息速率建议值 [#32-频道消息速率建议值] 频道消息速率是每秒内所有发布者(客户端和 RESTful API)向同一个频道发送的消息总条数。它是频道级限制,与[第 4 章](#4-客户端级限制)的客户端级限频分别计算:每个客户端都没有超限时,频道合计仍可能超出建议值。 建议值随频道同时在线人数分档。人数越多,每条消息的扇出成本越高,频道能承受的速率越低。 | 单个频道同时在线人数 | 频道消息速率建议上限 | | --- | --- | | < 1,000 | 200 条/秒 | | 1,000–10,000 | 100 条/秒 | | ≥ 10,000 | 30 条/秒 | 超出后的表现:通常不报错,但延迟可能增加,消息可能丢失,用户可能无法收发消息或反复重连。 接近建议值时: - 按用户分片到多个频道,每个频道独立对照上表。 - 高频小消息改用 Stream Channel + Topic(单频道不超过 128 人)。 - 在业务服务端聚合后通过 RESTful API 发送,减少上行条数。 - 需要更高速率时提前联系技术支持,可在不影响延迟和稳定性的前提下定制提升。 ## 4. 客户端级限制 [#4-客户端级限制] 以下限制均以单个 RTM 客户端实例为统计单位,多个客户端各自独立计算。 ### 4.1 调用频率限制 [#41-调用频率限制] RTM 将客户端 API 按功能分为若干操作类别,每个类别拥有独立的每秒调用配额。同一类别内的方法共享配额,不同类别之间互不影响。例如,同一秒内调用 15 次 `whoNow` 和 15 次 `getChannelMetadata` 不会触发限频,因为它们属于不同类别;但同一秒内调用 25 次 `whoNow` 会触发限频。 超出配额的调用不会被执行,也不会排队。SDK 通过错误回调返回限频错误码,需要在业务层节流或退避后重试,见[第 8 章](#8-超出限制后怎么办)。 #### 有特殊配额的操作 [#有特殊配额的操作] | 操作类别 | 方法 | 配额 / 客户端 | 类型 | 说明 | | --- | --- | --- | --- | --- | | 发送消息 | `publish` | 60 次/秒 | 默认上限 | Message Channel 与 User Channel 共用这 60 次。 | | 发送 Topic 消息 | `publishTopicMessage` | 200 次/秒,按单个 Stream Channel 计 | 默认上限 | 同一客户端加入多个 Stream Channel 时各自独立,不占用其他类别配额。 | | 修改频道属性 | `setChannelMetadata`、`updateChannelMetadata`、`removeChannelMetadata` | 20 次/秒 | 默认上限 | — | | 读取频道属性 | `getChannelMetadata` | 20 次/秒 | 默认上限 | — | | 修改用户属性 | `setUserMetadata`、`updateUserMetadata`、`removeUserMetadata` | 20 次/秒 | 默认上限 | — | | 读取用户属性 | `getUserMetadata` | 20 次/秒 | 默认上限 | — | | 获取锁 | `acquireLock` | 10 次/秒 | 默认上限 | — | #### 其余操作:每个类别各 20 次/秒 [#其余操作每个类别各-20-次秒] 下表每一行是一个独立类别,行内的方法共享该类别的 20 次/秒配额。 | 类别 | 方法 | | --- | --- | | 登录 | `login` | | 更新 Token | `renewToken` | | 订阅 Message Channel | `subscribe` | | 加入 Stream Channel | `join`、`leave` | | 加入 Topic | `joinTopic`、`leaveTopic` | | 订阅 Topic | `subscribeTopic` | | 订阅用户属性 | `subscribeUserMetadata` | | 查询频道在线用户 | `whoNow` | | 查询用户所在频道 | `whereNow` | | 修改临时状态 | `setState` | | 读取临时状态 | `getState` | | 设置锁 | `setLock` | | 删除锁 | `removeLock` | | 释放锁 | `releaseLock` | | 撤销锁 | `revokeLock` | | 查询锁 | `getLocks` | | 获取历史消息 | `getMessages` | ### 4.2 连接与实例 [#42-连接与实例] | 限制项 | 数值 | 类型 | 超出后 | | --- | --- | --- | --- | | RTM 实例数 / 客户端 | 1 个 | 固定上限 | 创建第 2 个实例失败。 | | `userId` 长度 | 64 个 ASCII 字符 | 固定上限 | 初始化或登录失败。 | | 同时订阅 Message Channel 数 | 50 个 | 默认上限 | 第 51 次 `subscribe` 失败并返回错误码。 | | 同时加入 Stream Channel 数 | 10 个 | 默认上限 | 第 11 次 `join` 失败并返回错误码。 | | 同时加入 Topic 数 / 频道 | 8 个 | 固定上限 | 第 9 次 `joinTopic` 失败。 | | 同时订阅 Topic 数 / 频道 | 50 个 | 固定上限 | 第 51 次 `subscribeTopic` 失败。 | | 订阅发布者数 / Topic | 64 个 | 固定上限 | 不传 `users` 时随机订阅至多 64 个发布者,超出的发布者消息收不到。 | ### 4.3 消息规格 [#43-消息规格] | 限制项 | 数值 | 类型 | 超出后 | | --- | --- | --- | --- | | 消息包体积(Message / User Channel) | 32 KB | 默认上限 | 发送失败,错误码 `-11010`。体积 = 消息负载 + `customType`。 | | 消息包体积(Topic) | 1 KB | 默认上限 | 发送失败,错误码 `-11010`。计算方式同上。 | | `customType` 长度 | 32 个 ASCII 字符 | 固定上限 | 发送失败。 | | 频道名长度 | 64 个 ASCII 字符 | 固定上限 | 调用失败;另受合法字符集约束,参见[频道命名指南](/zh-CN/realtime-media/rtm/build/channels-and-topics/channel-name)。 | | Topic 名长度 | 16 个 ASCII 字符 | 固定上限 | 调用失败。 | | `getMessages` 单次条数 | 100 条 | 固定上限 | 超出部分需翻页获取。 | | `getMessages` 查询窗口 | `start` 与 `end` 间隔不超过 24 小时 | 固定上限 | 调用失败并返回错误码。 | ### 4.4 Presence 规格 [#44-presence-规格] | 限制项 | 数值 | 类型 | 超出后 | | --- | --- | --- | --- | | `presenceTimeout` | 默认 300 秒,范围 5–300 秒 | 固定范围 | 不报错,就近取边界值。例如传 400 秒时按 300 秒生效。 | | 临时状态键值对数 / 用户 / 频道 | 32 对 | 固定上限 | `setState` 失败。 | | 临时状态单个 value 大小 | 16 KB | 固定上限 | `setState` 失败。 | | 临时状态 key 长度 | 32 个 ASCII 字符 | 固定上限 | `setState` 失败。 | | 加入频道前可缓存的临时状态数 | 100 个 | 固定上限 | 加入或订阅后才生效并触发通知。 | | `whoNow` 单页人数 | 100 人 | 固定上限 | 通过 `nextPage` 翻页。 | | 实时通知最大人数(Announce → Interval 切换阈值) | 默认 50 人,控制台可设 8–128 人 | 默认上限 | 在线人数达到阈值后,事件由实时通知改为周期聚合通知。 | ### 4.5 Storage 规格 [#45-storage-规格] | 限制项 | 数值 | 类型 | 超出后 | | --- | --- | --- | --- | | Metadata Item `key` 长度 | 32 个 ASCII 字符 | 固定上限 | 调用失败。 | | Metadata 组数 / 频道或用户 | 1 组 | 固定上限 | — | | Metadata Item 数 / 组 | 不限数量 | 不限数量 | 仍受整组 16 KB 约束。 | | 单组 Metadata 大小 | 16 KB | 默认上限 | 写入失败。 | | 单个 Metadata Item 大小 | 16 KB | 默认上限 | 写入失败;与整组 16 KB 同时生效。 | Metadata 写入后会长期保存,频道销毁或用户注销不会自动删除;不再需要时请显式删除。 ### 4.6 Lock 规格 [#46-lock-规格] | 限制项 | 数值 | 类型 | 超出后 | | --- | --- | --- | --- | | 同时持有锁数 / 客户端 | 不限数量 | 不限数量 | — | | 锁 TTL | 默认 10 秒,范围 10–300 秒 | 固定范围 | 不报错,就近取边界值。TTL 只在持有者掉线后开始计时;TTL 内重连回来仍持有锁,超时自动释放并触发事件。 | | 锁名长度 | 64 个 ASCII 字符 | 固定上限 | 调用失败。 | ## 5. RESTful API 限制 [#5-restful-api-限制] | 限制项 | 数值 | 类型 | 说明 | | --- | --- | --- | --- | | 账号总调用速率 | 1000 次/秒 | 默认上限 | 返回 HTTP 429,见[第 1 章](#1-账号级限制)。 | | `publish` 单频道速率 | 不单独设限 | — | RESTful API 发送量与客户端发送量一起计入[3.2 的频道消息速率](#32-频道消息速率建议值)。 | | `publish` 消息包体积 | 32 KB | 固定上限 | 超出会报错。 | | `publish` 请求体 | 可序列化字符串 | 固定上限 | 不支持二进制请求体;二进制内容请先进行 Base64 编码。 | | History 查询速率 | 60 次/秒 | 建议值 | 超出返回配额错误。 | | History 单次条数 | 100 条 | 固定上限 | 超出部分翻页获取。 | ## 6. 场景示例:怎么对照 3.2 做规划 [#6-场景示例怎么对照-32-做规划] 频道消息速率 ≈ 频道内活跃发布者数 × 人均每秒发送次数。先估算这个值,再对照[3.2 的分档表](#32-频道消息速率建议值)。分档表第一列是同时在线人数(决定扇出成本),第二列是发送速率,两者分别估算。 以下规模数字仅为演示,请用真实埋点数据替换: | 场景 | 示例规模 | 估算速率 | 对照 3.2 | 推荐做法 | | --- | --- | --- | --- | --- | | IM 群聊 | 500 人群,活跃时 5% 的人每 10 秒发 1 条 | 500 × 5% ÷ 10 ≈ 2.5 条/秒 | < 1,000 人档,上限 200,余量充足 | 使用 Message Channel;开启 Presence 时注意 5000 人建议值。 | | 直播间弹幕 | 5 万观众,1% 的人每 5 秒发 1 条 | 50,000 × 1% ÷ 5 = 100 条/秒 | ≥ 10,000 人档,上限 30,超出 3 倍以上 | 在业务服务端聚合,每秒合并为不超过 30 条后通过 RESTful API 下发,或按观众分片到多个频道;礼物等低频高价值消息单独使用一个频道。 | | 直播间礼物 / 系统通知 | 5 万观众,每秒不超过 5 条 | 5 条/秒 | ≥ 10,000 人档,上限 30,可承受 | 与弹幕分频道,避免被弹幕挤占。 | | 多人游戏状态同步 | 100 人房间,每人每秒 10 次位置上报 | 1,000 条/秒 | Message Channel 任何档位都超出 | 使用 Stream Channel + Topic;单频道不超过 128 人,每个发布者不超过 200 次/秒,接收端按需订阅不超过 64 个发布者。 | | IoT 设备上报 | 2,000 台设备,每台每 5 秒上报 1 次 | 400 条/秒 | 1,000–10,000 人档,上限 100,超出 4 倍 | 按设备分组到至少 5 个频道,每频道不超过 400 台、80 条/秒。 | | 协同编辑 / 白板 | 20 人协作,每人每秒 20 次笔画事件 | 400 条/秒 | < 1,000 人档,上限 200,超出 2 倍 | 使用 Stream Channel + Topic;Topic 消息不超过 1 KB,客户端合并 50 毫秒内的笔画后再发送。 | 两个提醒: - 活跃比例和人均频率对结果影响最大,优先用真实数据替换示例值。 - 分档表描述的是单个频道;分片后每个频道独立对照分档表,但项目级总上行速率(10 万条/秒,第 2 章)仍按所有频道合计。 ## 7. 常见问题 [#7-常见问题] 不是。限频按操作类别分别计算,20 次/秒是单个类别的默认配额。发送消息的 60 次/秒不占用其他类别的配额,反之亦然。 不是。Message Channel 和 User Channel 的 `publish` 共用同一个 60 次/秒配额。 客户端限频只是第一层。频道另有消息速率建议值(3.2),项目另有总上行 10 万条/秒(第 2 章)。多个客户端同时向一个频道高频发送时,单个客户端都没超限,频道合计仍可能超出建议值。 不是。200 次/秒按单个 Stream Channel 计算;同一客户端加入多个 Stream Channel 时各自独立。 不会。超出配额的调用不会被执行,SDK 返回错误,需要业务层重试。 “不限数量”只说明人数不设限,频道仍受 3.2 的消息速率建议值约束;开启 Presence 后,5000 人以上请提前联系技术支持。 不能。128 人是固定上限。需要更大规模时使用多个 Stream Channel 或改用 Message Channel。 Item 数量不设限,但整组 Metadata 和单个 Item 各受 16 KB 约束,两者同时生效。 没有这个单独限制。RESTful API 发送量与客户端发送量一起计入 3.2 的频道消息速率,RESTful API 本身受账号级 1000 次/秒约束。 不会。TTL 内重新回到频道仍持有该锁;超过 TTL 才自动释放并触发事件。 ## 8. 超出限制后怎么办 [#8-超出限制后怎么办] | 超限类型 | 怎么发现 | 要不要重试 | 建议做法 | | --- | --- | --- | --- | | 客户端类别配额超限(4.1) | SDK 错误回调,限频错误码 | 要 | 业务层做队列节流,指数退避后重试;不要在回调里立即重发。 | | 容量类固定上限(体积、长度、数量) | SDK 错误回调,例如 `-11010` 消息过长 | 不要 | 修正参数后再调用;发送前本地校验体积。 | | 参数范围类(`presenceTimeout`、锁 TTL) | 不报错,SDK 就近取边界值 | — | 按文档范围传值,不要依赖截断行为。 | | 频道消息速率建议值(3.2) | 不报错;延迟大幅上升,用户无法收发或反复重连 | — | 按 3.2 分片频道或改用 Stream Channel;需要更高值时联系技术支持。 | | 项目级建议值(PCU、总上行速率) | 不报错 | — | 预计超过时提前联系技术支持。 | | RESTful API 配额超限 | HTTP 响应返回配额错误 | 要 | 服务端限流并进行退避重试。 | 限频错误的重试模式(各平台 SDK 的回调形式见对应 API 参考): ```text send(msg): result = rtm.publish(channel, msg) if result.error == RATE_LIMITED: delay = min(baseDelay * 2 ** attempt, maxDelay) // 100 ms 到 2 s wait(delay) attempt += 1 if attempt < maxAttempts: send(msg) else: report("publish dropped after retries") else: attempt = 0 ``` 更稳妥的做法是在发送侧维护一个按类别的令牌桶(发消息 60 次/秒、其他类别 20 次/秒),从源头避免触发限频,而不是依赖重试。 ## 9. 申请提升与提前沟通 [#9-申请提升与提前沟通] 以下项目可以申请提升或需要提前沟通。请联系 `rtm-support@agora.io` 或技术支持,并附上 App ID、预计规模和上线时间: | 项目 | 默认值 | 类型 | | --- | --- | --- | | RESTful API 总调用速率 / 账号 | 1000 次/秒 | 申请提升 | | PCU / 项目 | 20 万 | 超出前提前沟通 | | 总上行消息速率 / 项目 | 10 万条/秒 | 超出前提前沟通 | | 开启 Presence 的频道订阅人数 | 5000 人 | 超出前提前沟通 | | 频道消息速率 | 见 3.2 分档表 | 可定制提升 | | 同时加入 Stream Channel 数 / 客户端 | 10 个 | 申请提升 | | 同时订阅 Message Channel 数 / 客户端 | 50 个 | 申请提升 | | `publish` 速率 / 客户端 | 60 次/秒 | 申请提升 | | `publishTopicMessage` 速率 / 客户端 / 频道 | 200 次/秒 | 申请提升 | | 消息包体积 | 32 KB / 1 KB | 申请提升 | | 单组 Metadata 大小 | 16 KB | 申请提升 | | 频道内锁数量 | 32 把 | 申请提升 | | Lock 总量 / 项目 | 100 万 | 申请提升 |