配额与限频
限制分两层：协议层硬限制（消息大小、频率、成员数等，来自冻结契约）与应用层配额/开关（控制台按应用配置，未开通返回 1021）。本页把两层放在一起，方便做容量与错误处理设计。
协议层硬限制
| 限制项 | 值 |
|---|---|
| 消息体 | 5120 字节 |
| 文本长度 | 5000 字符 |
| 单用户发送频率 | 120 条/分钟 |
| 输入状态频率 | 60 条/分钟 |
| 每会话离线消息 | 500 条 |
| 历史分页 | 默认 20 / 最大 100 |
| 普通群成员 | 3000 |
| 超级群成员 | 100000 |
| 聊天室在线 | 5000 |
| 撤回窗口 | 120000ms |
| 在线状态批量 / 订阅 | 100 / 500 |
| 已读明细分页 | 默认 50 |
| 合并转发 | 标题 64 字符 / 条目 100 / 正文 16384 字节 |
应用层配额与开关
服务开通、功能开关与配额在控制台管理（服务开通 / 配额 / 功能配置）。关闭服务后，对应接口返回 1021；超出配额返回 1025。
| 项 | 行为 | 错误码 |
|---|---|---|
| 服务未开通 | 接口拒绝，提示开通 | 1021 |
| 功能开关关闭 | 该能力不可用（如关闭群能力后建群失败） | 1021 / 1003 |
| 配额超限 | 调用被拒绝；可重试但需提额或降量 | 1025 |
| 发送频率超限 | 按窗口限流；响应可带 Retry-After | 1008 |
限频相关 HTTP 行为
| 项 | 值 |
|---|---|
| 状态码 | HTTP 429 |
| 业务码 | 1008（可重试） |
| 响应头 | Retry-After: 1（秒） |
| 默认限频 | 未配置时不做额外限频；客户端仍受协议层 120 条/分钟约束 |
| 按 operation 覆盖 | 控制台「接口调频」可按 operationId 设置 QPS |
JavaScript
// 统一处理限频：优先尊重 Retry-After，再指数退避
async function callWithBackoff(fn, maxAttempts = 4) {
for (let attempt = 0; ; attempt++) {
try {
return await fn();
} catch (error) {
const rateLimited = error?.status === 429 || error?.code === 1008;
if (!rateLimited || attempt >= maxAttempts) throw error;
const retryAfter = Number(error?.headers?.['retry-after'] || 1) * 1000;
await new Promise((r) => setTimeout(r, retryAfter * 2 ** attempt));
}
}
}容量与配额的关系
- 协议限制决定“单条消息/单用户”的上限；应用配额决定“整个应用”的上限；两者都要过。
- 限频是保护服务端的手段，不是业务特性：客户端必须做本地节流，不要靠捕获
1008来限速。 - 配额规划见 性能与容量：先算峰值入站/扇出，再核对配额与集群能力。