限流與應用狀態

為了保證服務穩定，每個應用的 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。併發連線數已滿時新的長連線被關閉，套餐不包含音影片時使用者不能發起和接聽通話。見數量上限。
• 與配額和執行策略的關係：啟用檔案儲存額度限制時，儲存容量、聊天室數同時受上表中平臺配額的限制，按兩者中較小的執行；每個群的人數、每人可加入的群數、訊息保留天數和音影片開關還可以在執行策略中設得更嚴格，按較嚴格的執行。
• 調低額度：已經超出的資料不受影響，只是不能再增加；訊息保留天數例外，縮短後超出保留期的訊息隨即不能再拉取，並被陸續刪除。
• 提高額度：請更換套餐，見更換套餐。

查詢目前的套餐

從服務端查詢應用目前的套餐、實際生效的額度和最近一天的用量，例如在使用者量接近上限前提醒營運人員。AI 程式設計助手用授權得到的服務端金鑰也透過它判斷額度夠不夠。

curl "$IM_API/$ORG/$APP/billing/plan" \
  -H "Authorization: Bearer $APP_TOKEN"

{
  "app_name": "demo",
  "plan": { "code": "std", "name": "标准版", "kind": "im" },
  "current_since": "2026-11-01",
  "period_last_day": null,
  "upcoming": [],
  "quotas": {
    "max_users": 100000, "max_connections": 5000, "max_groups": 0, "max_group_members": 0,
    "max_groups_per_user": 0, "max_message_retention_days": 7, "max_storage_gb": 100,
    "max_concurrent_calls": 20, "max_chatrooms": 0, "max_group_call_participants": 0,
    "rtc_enabled": true, "max_game_online": 0, "max_game_room_players": 0
  },
  "entitlements": { "chatroom": true, "game_room": false, "ai_bot": true },
  "storage_quota_enabled": true,
  "latest_usage": {
    "date": "2026-11-15", "registered_users": 1234, "peak_connections": 4812, "dau": 980,
    "messages": 56120, "chatroom_peak_connections": 0, "game_player_minutes": null,
    "storage_gb": 3, "storage_bytes": 2899102924
  }
}

欄位	說明
plan	套餐的編碼、名稱和類型（im 即時通訊、game 遊戲）
current_since、period_last_day	目前套餐的生效日期；按期購買的套餐有最後一天，沒有期限的為 null
upcoming	已經約定、將來生效的套餐（plan_code、plan_name、effective_from）
quotas	實際生效的額度（已包含平臺為這個應用單獨調整的部分）。0 表示不限；max_game_room_players 為 0 時按協議上限 10 人；未啟用檔案儲存額度限制時 max_storage_gb 為 0
entitlements	各項功能是否可用，如 game_room 遊戲房間、chatroom 聊天室、ai_bot AI 機器人
latest_usage	最近一個統計日（最晚到昨天）的用量，沒有統計時為 null，未採集到的項為 null。是日統計，不是即時值：每天凌晨採集前一天

• 只返回權杖所屬應用的資料，不含價格、餘額和帳單；更換套餐、檢視帳單請在控制檯操作。
• 計入 OpenAPI 呼叫額度。

應用和租戶的狀態

租戶可以在控制檯停用應用；平臺在發現違規或風險時，可以暫停應用或租戶，或者把應用設為只讀；租戶欠費時，應用會變為只讀，之後租戶會被暫停，見欠費。各種狀態對 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 頻道准入

• 頻道和通話共用兩項限制：一個使用者同時只能在一個通話或頻道中；應用的併發通話額度由兩者合計。
• 頻道數、人數和請求頻率見使用限制。
• 新的加入受平臺的頻道總開關和應用的頻道開關控制，應用的開關預設開啟。關閉任一開關不會立即結束已有的會話。
• 應用只讀、關閉了音影片策略或套餐不允許音影片時，已有頻道中的會話不能再續發媒體憑據；退出等清理操作仍然可以進行。