限流与应用状态
为了保证服务稳定，每个应用的 OpenAPI 调用都有频率上限（配额），超出时返回 429 rate_limited。应用或租户被停用、暂停或设为只读时，OpenAPI 也会拒绝部分或全部请求。本页说明这些规则，以及收到相应的错误后该怎么处理。好友数、群人数等数量上限见使用限制；注册用户数、并发连接数等应用级的额度由应用的套餐决定，见套餐的额度。
OpenAPI 调用额度
每个应用的 OpenAPI 请求共用一份额度：每秒 rest_qps_limit 次，默认 1200 次，突发量与它相同。
- 计入的请求：这个应用的全部 OpenAPI 请求，包括查询；以及凭据校验通过后的换取 App Token 请求，两者共用同一个计数。多台服务器、多个 App Token 发出的请求合并计算。
- 不计入的请求：没有通过鉴权检查的请求，即 App Token 无效、不属于该应用、来源 IP 不在白名单内、租户或应用不可用的请求。用户在客户端调用的接口另有一份额度，见应用的其他配额。
- 批量接口按项数计入：一次处理多项的接口按项数计算，例如一次批量创建 100 个用户计为 100 次，批量发送消息按接收人数计算，批量添加群成员按人数计算。一个请求最多计到应用每秒的额度，额度较小的应用也能使用批量接口。额度不足时整个请求返回
429 rate_limited，其中的任何一项都没有执行。 - 换取 App Token 另按来源 IP 限制：每个 IP 每分钟最多 120 次，参数错误、凭据错误的请求也计入。App Token 默认 7 天有效，请缓存复用，不要每次调用前都换取。
限流的计算方式
本服务的限流按“匀速恢复、允许突发”的方式计算。可以把额度想象成一个最多存放 N 次的桶：每个请求取走 1 次，桶以每个周期 N 次的速度匀速补充，桶空时请求被拒绝。因此：
- 空闲一段时间后，可以连续发出 N 次请求（突发）；
- 额度用完后，每隔“周期 ÷ N”恢复 1 次，例如每秒 1200 次的额度约每 0.83 毫秒恢复 1 次；
- 长时间来看，平均速率不超过每个周期 N 次；
- 在任意一段长度为一个周期的时间内，最多可能放行约 2N 次：先用完桶里存着的 N 次，同一段时间内又恢复了 N 次。
例如在默认额度下持续高并发地调用，第一秒约有 2400 次成功，之后稳定在每秒约 1200 次，其余的请求返回 429。
文档中“每分钟 N 次”“每天 N 次”这类限制，除非另有说明，都按同样的方式计算：可以连续用完 N 次，之后每隔“周期 ÷ N”恢复 1 次。例如换取 App Token 每个 IP 每分钟 120 次，用完后每 0.5 秒恢复 1 次。
被拒绝时返回 429 rate_limited，响应头 Retry-After 为恢复足够的额度需要等待的秒数，向上取整，至少为 1。OpenAPI 的额度按秒计算、恢复很快，Retry-After 通常为 1：
HTTP/1.1 429 Too Many Requests
Content-Type: application/json; charset=utf-8
Retry-After: 1
X-Request-Id: GJJ3W5Z3NWMWF56NNGGWDZWWYO
{
"error": {
"code": "rate_limited",
"message": "请求过于频繁，请稍后重试",
"request_id": "GJJ3W5Z3NWMWF56NNGGWDZWWYO"
}
}应用的 OpenAPI 额度用完时没有 details；消息、聊天室等相关的限制带 details.reason，见错误码。
为了避免触发限流：
- 缓存 App Token，不要每次调用前都换取；
- 在服务端用队列控制调用速率，批量导入、群发通知这类后台任务与线上请求分开排队，放在业务低峰期执行，避免挤占线上请求的额度；
- 收到
429后按Retry-After等待，不要立即重试；多个工作线程应共同遵守这个等待时间，而不是各自重试。
应用的其他配额
除 OpenAPI 调用额度外，每个应用还有以下配额，由平台设置：
| 配额 | 默认值 | 说明 | 超出时 |
|---|---|---|---|
每分钟消息数 msg_per_min_limit | 30000 | 应用内客户端和服务端发送的消息合计；批量发送按接收人数计入，只推在线的消息也计入，群提示等系统消息不计入 | 429 rate_limited，details.reason 为 app_message_rate |
客户端每秒请求数 client_qps_limit | 1200 | 用户在客户端调用的接口和长连接上的请求合计，与 OpenAPI 分开计算；通话的长连接请求和通话心跳也计入，长连接上进入、离开聊天室和发送聊天室消息不计入（它们另有聊天室的限流）。登录和续期另有一份同样大小的额度；新建长连接的速率也是每秒这么多条，单独计算 | 429 rate_limited |
存储额度 storage_limit_gb | 1024 GB | 应用中可用的文件（附件、头像、聊天室封面、群文件，含图片的缩略图）占用的空间合计，1 GB 按 230 字节计；已删除、被屏蔽的文件和未完成的上传不计入。实际的额度取它与套餐的存储容量中较小的一个。创建上传时检查“当前用量 + 这次的大小”，超出时拒绝新的上传，不影响下载和已有的文件。同时进行的多个上传可能让用量略超额度。当前用量和额度可以通过存储用量查询 | 409 limit_exceeded，details.reason 为 storage_quota |
聊天室数 chatroom_limit | 10000 | 应用中未解散的聊天室数，实际的上限取它与套餐的聊天室数中较小的一个；为 0 时不能再创建聊天室 | 409 limit_exceeded，details.reason 为 chatroom_limit |
每秒聊天室消息数 chatroom_msg_per_sec_limit | 2000 | 应用全部聊天室每秒接受的消息数合计，客户端和服务端发送的都计入，高、普通、低三种优先级都计入；不计入每分钟消息数 msg_per_min_limit | 429 rate_limited，details.reason 为 room_send_rate；低优先级的消息被丢弃，不返回错误 |
每分钟推送数 push_per_min_limit | 60000 | 应用每分钟发出的离线推送，按设备计：消息和好友、群的通知计入，来电、撤回后的更新和测试推送不计入；为 0 时停止推送 | 不返回错误：超出的设备这次不推送，在推送统计中记为 rate_limited |
回调每秒请求数 callback_qps_limit | 500 | 应用全部回调地址合计每秒发出的事件回调请求数，每个地址的每秒请求数上限不能超过它，见回调地址 | 不返回错误：超出的事件在队列中等待，晚一些发出，不会丢弃 |
此外，以下与 OpenAPI 有关的频率限制是固定的：
| 限制 | 数值 | 超出时 |
|---|---|---|
| 每个群的消息数 | 每秒 40 条，客户端和服务端发送的合计 | 429 rate_limited，details.reason 为 group_send_rate |
| 计算密码哈希（带密码创建用户、设置密码） | 每个应用每秒 100 次，OpenAPI 和控制台合计 | 429 rate_limited；批量创建用户时超出的用户出现在失败的项中 |
| 换取 App Token | 每个来源 IP 每分钟 120 次 | 429 rate_limited |
| 完成上传时的图片处理 | 服务繁忙时等待最多 5 秒，仍然繁忙则拒绝，文件仍在上传中，稍后重新完成即可 | 429 rate_limited，details.reason 为 image_busy |
| 每个聊天室的高优先级消息 | 每秒 20 条，客户端和服务端发送的合计。普通和低优先级的消息由运行策略 chatroom_msg_per_second 限制，见聊天室消息 | 429 rate_limited，details.reason 为 room_send_rate |
| 每个聊天室的属性写入 | 每秒 20 次，客户端和服务端合计 | 429 rate_limited，details.reason 为 room_attribute_rate |
| 代用户举报 | 每个应用每分钟 600 次 | 429 rate_limited，details.reason 为 request_rate |
按用户的频率限制（如每个用户每秒发送的消息数、每天发送的好友申请数、每天上传的文件数和数据量）只对用户在客户端的操作生效，服务端代用户操作不受这些限制，数值见使用限制。服务端上传文件、换取下载地址只计入 OpenAPI 调用额度，一次换取多个下载地址也只计一次。
套餐的额度
上面的配额是平台为保护服务稳定设置的上限。此外，应用的注册用户数、并发连接数、群总数、每个群的人数、每人可加入的群数、消息保留天数、存储容量、并发通话数、聊天室数，以及能否使用音视频，由应用的套餐决定，可以在控制台应用详情的“套餐与用量”中查看。
- 用满时：相应的操作被拒绝，一般返回
409 limit_exceeded，details.reason说明是哪一项，如app_group_limit、storage_quota、chatroom_limit；注册用户数已满时没有details。并发连接数已满时新的长连接被关闭，套餐不包含音视频时用户不能发起和接听通话。见数量上限。 - 与配额和运行策略的关系：存储容量、聊天室数同时受上表中平台配额的限制，按两者中较小的执行；每个群的人数、每人可加入的群数、消息保留天数和音视频开关还可以在运行策略中设得更严格，按较严格的执行。
- 调低额度：已经超出的数据不受影响，只是不能再增加；消息保留天数例外，缩短后超出保留期的消息随即不能再拉取，并被陆续删除。
- 提高额度：请更换套餐，见更换套餐。
应用和租户的状态
租户可以在控制台停用应用；平台在发现违规或风险时，可以暂停应用或租户，或者把应用设为只读；租户欠费时，应用会变为只读，之后租户会被暂停，见欠费。各种状态对 OpenAPI 的影响如下：
| 状态 | 换取 App Token | 已签发的 App Token | 调用 OpenAPI | 恢复后 |
|---|---|---|---|---|
| 正常 | 正常 | 有效 | 正常 | — |
| 限流（平台标记） | 正常 | 有效 | 与正常相同，各项配额照常执行；平台可能同时调低应用的配额 | — |
| 只读（平台设置或租户欠费） | 正常 | 有效 | 查询和处置类操作正常；新增数据、修改资料的写操作返回 403 app_unavailable，只因欠费时 details.reason 为 arrears | 无需处理，写操作恢复正常 |
| 应用停用（在控制台停用） | 403 app_unavailable | 立即失效 | 401 unauthenticated | 启用后重新换取 App Token |
| 应用被平台暂停服务 | 403 app_unavailable | 立即失效 | 401 unauthenticated | 平台恢复后重新换取 App Token |
| 租户暂停（平台暂停或欠费暂停） | 403 tenant_unavailable，只因欠费时 details.reason 为 arrears | 立即失效 | 401 unauthenticated | 恢复后重新换取 App Token |
| 租户处于注销冷静期 | 403 tenant_unavailable | 立即失效 | 401 unauthenticated | 撤销注销后重新换取 App Token |
| 应用已删除 | 401 invalid_client | 永久失效 | 401 unauthenticated，details.reason 为 app_deleted | 不能恢复 |
| 租户已注销 | 401 invalid_client | 永久失效 | 401 unauthenticated，details.reason 为 tenant_closed | 不能恢复 |
- 状态变化的生效时间：通常立即生效，最迟约 30 秒。
- 停用和暂停后的现象：已签发的 App Token 全部失效，所以先收到
401 unauthenticated，重新换取时再收到403 app_unavailable或403 tenant_unavailable。这时不要反复换取，请告警，按较长的间隔（如几分钟）再尝试，并在控制台查看租户和应用的状态。 - 恢复后：之前签发的 App Token 不会恢复有效，重新换取一次即可，Client ID 和 Client Secret 不变。
- 只读状态：被拒绝的写操作包括创建用户和修改用户资料，添加好友和修改好友备注、自定义属性，建群、加人、修改群资料和成员属性，发送、编辑和置顶消息，创建上传（已经创建的上传仍可以完成），创建聊天室、修改聊天室资料、设置聊天室属性、加入聊天室白名单和发送聊天室消息。查询，以及封禁、禁言、踢下线、修改密码、删除用户、删除好友、拉黑、移出群成员、解散群、撤回和删除消息、标记已读、换取下载地址和删除文件，聊天室的封禁、解散和成员处置，结束通话和移出通话成员等操作仍然可以执行：它们不增加数据，或是处置违规内容所必需的。具体以各接口文档为准。
- 对用户的影响：应用停用、暂停或租户暂停、处于注销冷静期时，用户的 User Token 同样失效，长连接被断开，不能登录和收发消息，也不能换取文件的下载地址（已经换到的下载地址在到期前仍可使用，头像的公开地址仍可访问），进行中的通话随之结束，恢复后客户端续期即可，不必重新登录；只读状态下用户保持连接，可以查看消息、进入聊天室、接听和加入通话，但不能发送消息（包括聊天室消息）、发起通话和在群通话中邀请他人。应用删除、租户注销后，用户的令牌永久失效。
- 离线推送和事件回调：应用停用、暂停或租户暂停、处于注销冷静期时，不发送离线推送（撤回后更新通知照常发送），也不生成新的事件回调，期间没有推送和回调的事件恢复后都不补发，见应用状态的影响和不回调的情况。只读状态下推送和回调照常。
欠费
已出账的账单过了付款截止时间仍未付清即为逾期。默认从最早一张逾期账单的付款截止时间起算，15 天后租户的全部应用变为只读，30 天后暂停租户的服务，与我们另有约定的以合同为准；生效前 3 天会通知账单联系人。这两种状态下 app_unavailable、tenant_unavailable 的 details.reason 为 arrears。
逾期的账单全部结清后，只读和暂停自动解除，通常在记录收款后几秒内生效：只读解除后写操作随即恢复；暂停解除后重新换取 App Token 即可。受限制期间照常计费。详见逾期与欠费。
申请提高配额
上限分两类，提高的方式不同：
- 数量额度：注册用户数、并发连接数、群总数、存储容量、并发通话数、聊天室数等套餐的额度，需要更高时请更换套餐，见更换套餐。存储容量和聊天室数同时受平台配额的限制（默认 1024 GB、1 万个），需要超过时请在联系我们时一并说明。
- 保护性配额：OpenAPI 调用额度和应用的其他配额，如每秒请求数、每分钟消息数、每分钟推送数，与价格无关，由平台按业务需要调整。
默认的保护性配额能满足大多数应用。如果你的业务需要更高的配额，例如大规模导入数据、高峰期群发通知、大量用户在短时间内同时上线，请联系我们，并提供：
- 应用的 AppKey；
- 需要调整的配额和期望的数值；
- 业务场景和预计的峰值调用量。
配额和套餐的额度调整后很快生效（配额最迟约 30 秒，套餐通常几秒内），不需要重新换取 App Token。
RTC 频道准入
频道和原通话共享同用户媒体占用与应用媒体并发额度。频道数量、人数和请求频率见频道限制。新加入还需频道灰度；关闭灰度不会立刻结束已有会话。应用只读、RTC 策略关闭或套餐不允许时，已有频道不能续发媒体凭据；退出等清理操作仍可进行。