API 语义与限制
本页把“能调多快、能翻多少、能发多大、失败了怎么办”集中说明：速率与配额、分页、消息体、幂等与 Nonce、回调重试语义、错误码分组。数值优先取自 IDL（protocol.limits / openapi.common / callbacks.delivery / errors）；IDL 未声明的接口级实现细节会明确标注“未声明”，不虚构 QPS。
协议容量限制
| 项目 | 值 | 说明 |
|---|---|---|
| 单条消息体上限（字节） | 5,120（5.0 KiB） | 按消息内容序列化后的 UTF-8 字节数校验，超出返回 1007 |
| 文本消息字符上限 | 5,000 | — |
| 单会话离线消息上限（条） | 500 | — |
| 历史消息默认分页大小 | 20 | — |
| 历史消息最大分页大小 | 100 | — |
| 普通群成员上限 | 3,000 | — |
| 超级群成员上限 | 100,000 | — |
| 聊天室在线人数上限 | 5,000 | — |
| 撤回时限（毫秒） | 120,000（2 分钟） | 超过撤回时限返回 1022 |
| 正在输入上报频率上限（次/分钟） | 60 | — |
| 消息发送频率上限（条/分钟） | 120 | 客户端发送频率上限；超出通常返回 1008 |
| 批量在线状态查询上限 | 100 | — |
| presenceSubscriptionsMax | 500 | — |
| 已读用户列表默认分页大小 | 50 | — |
| combineTitleChars | 64 | — |
| combineItemsMax | 100 | — |
| combineTextBytes | 16,384（16.0 KiB） | — |
鉴权时间窗口
| 项目 | 值 | 说明 |
|---|---|---|
| 时间戳允许窗口 | 300,000 毫秒（5 分钟） | Timestamp 与服务器时间偏差超限返回 1019 |
| Nonce 有效期 | 300,000 毫秒（5 分钟） | 同一 Nonce 有效期内重复使用返回 1020 |
| Nonce 长度 | 8-64 字符 | 长度不合法按 1018 INVALID_SIGNATURE 处理 |
速率限制与配额
Open API 没有在 IDL 中声明的全局 QPS 数值；限频由运行时配置决定，默认关闭。可以按 operationId 配置 QPS 覆盖，超限统一返回 HTTP 429 + 1008 + Retry-After: 1。
| 范围 | 限制 | 来源 / 行为 |
|---|---|---|
| 客户端消息发送 | 120 条/分钟 | protocol.limits.sendRatePerMinute；超出按 1008 处理 |
| 客户端“正在输入” | 60 次/分钟 | protocol.limits.typingRatePerMinute |
| Open API 接口级 QPS | 默认不限频；可按 operationId 覆盖 1–10000（0/省略=该接口不限） | Admin API POST /api/admin/apps/{appkey}/ratelimit（overrides） |
| 超限响应 | HTTP 429 + code 1008 + Retry-After: 1 | 可退避重试；响应仍保留统一信封 |
| 配额用尽 | HTTP 429 + code 1025 | 可退避重试或在控制台调整配额 |
| 服务未开通 | HTTP 403 + code 1021 | 不是频率问题，重试无效 |
未声明的限制
IDL 未声明各接口默认 QPS、并发连接数上限或按应用的全局 TPS；实际限频以部署配置（ratelimit 覆盖）为准。不要按“固定 QPS”做容量承诺。
分页上限
| 项目 | 值 | 说明 |
|---|---|---|
| 单页最大条数 | 100 | IDL 统一上限，具体接口可更小 |
| 历史消息默认条数 | 20 | 不传 limit 时的默认值 |
| 历史消息最大条数 | 100 | limit 超出时按接口实现截断或报错 |
| 已读用户默认条数 | 50 | 已读用户列表默认分页大小 |
| 游标参数 | beforeSeq（uint64，可选） | 按会话内 seq 向前翻页 |
| 聊天室/群成员分页 | 接口级 limit（见各接口 desc） | 如群成员默认 100、上限 500；超出按接口校验 |
帧与传输限制
| 项目 | 值 | 说明 |
|---|---|---|
| 单帧上限 | 65,536 字节（64.0 KiB） | WebSocket 帧编码与长度校验（客户端长连接） |
| 帧编码 | json-utf8 | 二进制/JSON 帧编码 |
| WS 路径 | /ws | 客户端连接端点，与 Open API 分离 |
| 握手查询参数 | token、appkey | 客户端建连时携带 |
幂等与 Nonce
写操作的幂等分两层：传输层用 Nonce 防重放，业务层用业务键去重。两者都不能替代对方的语义。
| 层 | 规则 | 失败表现 |
|---|---|---|
| Nonce（传输层） | 每次请求新随机串（8–64 字符），300,000 毫秒（5 分钟） 内不可复用；只解决“同一请求被重放” | 1020 NONCE_REPLAYED |
| Timestamp（传输层） | epoch 毫秒，偏差不超过 ±300,000 毫秒（5 分钟） | 1019 TIMESTAMP_EXPIRED |
| 业务幂等键 | 写操作可带 clientMsgId（消息）/requestId（幂等键，24h）；非幂等接口重复调用语义在各 operation.desc 标注 | 重复调用是否安全取决于具体接口 |
| IDL 标注幂等 | 54 / 230 个 Open API 标注 idempotent | 未标注的接口重复调用需业务去重 |
幂等接口分布
重试建议：网络超时/连接中断先按业务幂等键确认是否已成功（消息用 clientMsgId，查询类接口可直接重试）；命中 1008/1025/2xxx 时按指数退避重试。完整 SDK 实现见 Node.js App Server SDK。
回调重试语义
回调是“至少一次投递”：应用服务器必须校验签名、快速返回 2xx，并基于 eventId 幂等去重。失败重试与超时参数如下（来自 callbacks.delivery）。
| 项 | 值 | 说明 |
|---|---|---|
| 投递方式 | POST application/json; charset=utf-8 | 每次投递一个事件 |
| 单次超时 | 5,000 毫秒（5 秒） | 超时按失败计 |
| 成功判定 | HTTP 2xx | 非 2xx 触发重试 |
| 最大尝试次数 | 3 | 含首次投递 |
| 退避间隔 | 1,000 / 5,000 / 30,000 毫秒 | 按失败次数递增 |
| 触发条件 | non-2xx、timeout、network-error | 网络错误/超时/非 2xx |
| 请求体上限 | 262,144 字节（256.0 KiB） | 超出视为不可投递 |
| 单应用并发 | 8 | 并发投递数 |
| 顺序 | 同事件类型内近似有序，不保证全局顺序；eventId 幂等去重由应用服务器负责 | 不保证全局顺序 |
| 去重键 | eventId | 应用侧必须自行幂等 |
回调失败可在 投递日志 查询并手动 重试；重试语义与自动重试一致。
错误码分组
错误码按 IDL 约定分四段，重试策略只需看前缀：1xxx 基本不可重试（1008 除外），2xxx 可重试，3xxx 是 SDK 本地错误、不来自服务端。
| 区间 | 含义（IDL） | 错误码数 | 其中可重试 |
|---|---|---|---|
0 | 成功 | 0 | 0 |
1xxx | 客户端/参数/权限类错误（不可重试，除 1008） | 35 | 2 |
2xxx | 服务端/依赖类错误（可重试） | 4 | 4 |
3xxx | SDK 本地错误（不来自服务端） | 4 | 3 |
按类别汇总：客户端 / 参数 / 权限 30 个；Open API 签名与开通 5 个；服务端 / 依赖 4 个；SDK 本地 4 个。完整列表与 HTTP 状态见 状态码与错误码。
接口级限制
以下限制来自各接口的 IDL 说明（desc / 请求体字段说明），按接口标注：
| 接口 | 限制说明 |
|---|---|
message.history.get | limit：默认 20，上限 100 |
group.members.list | limit：默认 100，上限 500 |
chatroom.keepalive | 刷新聊天室空闲销毁时间（默认 30 分钟无活动销毁）。 |
presence.batch | 批量在线状态（<=100）。 |
sensitive-word.set | 覆盖设置敏感词（<=500 词，单词 <=64 字符）与处置动作。 |
stats.trend | days：默认 7，上限 90 |
user.batch.get | 批量获取用户资料（上限 100；不存在的 userId 返回在 missing）。 |
user.tag.set | 设置用户标签（全量覆盖，最多 20 个，每个 ≤32 字符）。 |
user.tag.batch.set | 批量设置用户标签（上限 100 条，返回 updated/failed）。 |
conversation.tag.set | 将会话归入标签（同一会话可属多个标签，最多 20 个）。 |
user.ban.list | limit：默认 50，上限 100 |
user.subscription.set | 设置用户订阅关系（全量覆盖，最多 100 个）。 |
group.import | 批量导入群组（上限 50，逐条幂等；返回 imported/failed）。 |
chatroom.destroy.policy.set | 设置聊天室销毁策略（idle=空闲销毁，idleMs 默认 1800000；fixed=定时销毁，destroyAt 由创建时间+idleMs 计算）。 |
message.reaction.batch | 批量查询多条消息的回应摘要（上限 50）。 |
chatroom.members.existsBatch | 批量查询用户是否在聊天室中（单次 <=1000；isInChrm 1=在 0=不在）。覆盖融云 /chatroom/users/exist.json。 |
chatroom.globalMute.set | 全局禁言用户：应用下所有聊天室生效，仅约束客户端发送；单次 <=20 用户，minute 1..=43200。覆盖融云 /chatroom/user/ban/add.json。 |
chatroom.globalMute.remove | 解除用户全局禁言（单次 <=20 用户；幂等）。覆盖融云 /chatroom/user/ban/remove.json。 |
chatroom.messageWhitelist.add | 添加消息类型到聊天室消息白名单（应用级共享，<=20 种，标识 <=32 字符；重复添加幂等）。覆盖融云 /chatroom/whitelist/add.json；路径带 .json 以避开 rev4 用户白名单占用的 /chatroom/whitelist/add。 |
sensitiveword.add | 增量添加敏感词（不覆盖既有词，重复添加幂等；单词 <=32 字符，总数 <=500）。覆盖融云 /sensitiveword/add.json；replaceWord 会把应用处置动作切换为 replace。 |
sensitiveword.batch.add | 批量增量添加敏感词（1..=50 条，合并既有列表，总数 <=500）。words 支持字符串或 {word,replaceWord} 对象。覆盖融云 /sensitiveword/batch/add.json。 |
message.history | 分页查询应用历史消息审计记录（userId/conversationType/targetId/from/to 过滤；page 从 1 开始，size 上限 100）。审计视图由已持久化消息派生，聊天室等 ephemeral 消息不在范围内。 size：默认 20，上限 100 |
chatroom.entry.batch.set | 批量设置聊天室自定义属性（按 entryOwnerId 隔离，单次 <=100 对；同 key 覆盖）。覆盖融云 /chatroom/entry/batch/set.json。 |
chatroom.entry.batch.remove | 批量移除聊天室自定义属性（<=100 个 key，按 entryOwnerId 隔离，幂等）。覆盖融云 /chatroom/entry/batch/remove.json。 |
entrust.joined.group.query | 分页查询用户加入的群（page/size；role 0=全部/1=成员/2=管理员/3=群主；order 0=正序/1=倒序，默认倒序；size 上限 100）。覆盖融云 /entrust/joined/group/query.json。 size：默认 50，上限 100 |
ultragroup.banned.whitelist.add | 把用户加入超级群全体禁言白名单（userIds 支持数组或逗号分隔字符串，单次 <=20，幂等，白名单总人数 <=1000）；白名单成员在全体禁言期间仍可发送。覆盖融云 /ultragroup/banned/whitelist/add.json。 |
ultragroup.banned.whitelist.del | 把用户移出超级群全体禁言白名单（单次 <=20，幂等；不存在时 removed=0）。覆盖融云 /ultragroup/banned/whitelist/del.json。 |
ultragroup.banned.whitelist.get | 分页查询超级群全体禁言白名单（page 从 1 开始，pageSize 默认 50、上限 200；同时返回 users[{id}] 与 userIds）。覆盖融云 /ultragroup/banned/whitelist/get.json。 |
ultragroup.userbanned.add | 禁言指定超级群成员（userIds 单次 <=20，duration 秒可选，缺省永久；群级写入既有成员禁言 Group.muted 并真实拦截发送；单群禁言人数 <=100）。频道级（channelId）仅保存状态。覆盖融云 /ultragroup/userbanned/add.json。 |
ultragroup.userbanned.del | 解除指定超级群成员禁言（单次 <=20，幂等；不存在时 removed=0）。覆盖融云 /ultragroup/userbanned/del.json。 |
ultragroup.userbanned.get | 分页查询被禁言的超级群成员（含 until 到期时间与 permanent 标记；pageSize 默认 50、上限 100）。覆盖融云 /ultragroup/userbanned/get.json。 |
bot.integration.create | 为已存在的机器人（bot.create 产出）登记 Webhook 回调集成：每个机器人一份配置、应用内 <=10 份；events 取 bot.message.private / bot.message.group / bot.message.chatroom / bot.chatroom.user.join。secret 缺省自动生成；回调签名与既有回调一致。覆盖融云 /v3/bot/integration/create.json。 |
conversation.tag.create | 创建会话标签：tagName ≤16 字符；tagId 可选（≤32 字符，[A-Za-z0-9_.-]，缺省由 tagName 派生）；单用户最多 20 个标签（超出 1031）。覆盖融云 /conversation/tag/create.json。 |
conversation.tag.conversations.add | 把会话加入标签：单次 ≤100 条（items 支持对象数组或 "type:target" 字符串），幂等；单标签最多 1000 个会话（超出 1033）。覆盖融云 /conversation/tag/conversations/add.json。 |
conversation.tag.conversations.remove | 把会话移出标签：单次 ≤100 条，幂等。覆盖融云 /conversation/tag/conversations/remove.json。 |
conversation.tag.conversations.get | 分页查询标签内会话（含 top、unreadCount、lastMessageAt；limit 默认 50 上限 200）。覆盖融云 /conversation/tag/conversations/get.json。 |
限频与错误码
1008RATE_LIMITED：请求频率超过限制，HTTP 429，可退避重试（响应带Retry-After: 1）。1025QUOTA_EXCEEDED：配额用尽，HTTP 429，可退避重试或在控制台调整配额。1007MESSAGE_TOO_LARGE：消息体超过 5,120 字节（5.0 KiB），HTTP 400，不可重试。1015MEMBERSHIP_LIMIT：群成员数超过上限（普通群 3,000，超级群 100,000）。
相关说明
- 鉴权与签名：请求头、签名算法与鉴权失败错误码
- 请求与响应数据格式：JSON 请求体、响应信封与分页
- 状态码与错误码：全部错误码、HTTP 状态与重试建议
- 限频、配额与容量限制：协议限制与分页上限
- Node.js App Server SDK：内置重试与错误映射
- WebSocket 协议：帧结构与客户端频率限制