sometimeslimits and reliability
these limits apply to API 1. inspect GET /limits and response headers to adapt to your installation’s current allowance.
rate limits
limits apply simultaneously at application, installation, user and resource levels. token rotation and multiple installations cannot bypass an application or user quota. return RateLimit-Limit, RateLimit-Remaining, RateLimit-Reset and RateLimit-Bucket headers; 429 additionally includes Retry-After in seconds and retry_after_ms in the error. use returned values rather than relying on wall-clock alignment. GET /limits returns current limits, permitted field enums and remaining storage quotas for the current installation without unrelated account data.
scroll the table horizontally to see all columns.
| bucket | initial limit | scope |
|---|---|---|
| REST requests | 50/second, burst 100 | application |
| REST requests | 10/second, burst 20 | installation |
| message-like writes | 5 per 5 seconds, burst 5 | application + installer + chat; includes media/polls/private replies |
| notifications | 5/hour and 20/day | application + installer |
| friend requests / group invitations | 10/hour | application + installer, plus existing account limits |
| call starts / invitations | 5 per 10 minutes | application + installer + chat |
| drawing previews | 10/second | installation + chat |
| JSON request | 256 KiB; profile writes 1,756,384 bytes; SDP 64 KiB | request |
| gateway inbound frame | 64 KiB; 120/minute except heartbeat ACK and event ACK | application connection |
| simultaneous uploads | 3 | installation; reservation-aware |
| uploaded bytes | 500 MiB/day | application + installer, plus asset/user quotas |
| active call sessions | 1 per installation; 20 per application | v1 self-service default |
| bot applications / private invites | 10 per developer / 1,000 per application | owner/application |
| installations | 100 active per user; 10,000 per application | v1 self-service default |
storage and event budgets
replay stores at most 10,000 events per installation and 100,000 per application for 24 hours, with a 64 KiB event payload cap. oversized changes emit {resource_id,revision,fetch_required:true} instead of the body; fetching still requires current grants. private message bodies expire at their TTL, independent of replay. idempotency receipts last 24 hours; never store secrets or unredacted private content in request logs. activity metadata lasts 90 days and contains action, actor, application, resource IDs, timestamp, result and changed field names, not old/new message or profile bodies.
retry and conflict handling
retry network failures, 429 and 503 with bounded exponential backoff and jitter, honoring Retry-After. retain the original idempotency key for uncertain POST outcomes. do not automatically merge a 412 by overwriting a user’s more recent edit; reread and reconcile only intended fields. installation revocation is permanent until a new human authorization. transient gateway interruption does not grant permission to repeat non-idempotent actions.
abuse handling
publication has no approval queue, but existing platform content rules, account restrictions and abuse controls still apply. users can block, disable or uninstall bots; group owners can exclude them; platform staff can disable abusive applications after publication. grant checks are enforced server-side even when clients are old or malicious. rate-limit reservations and upload quotas apply across concurrent tokens. developers cannot buy or declare their way around consent in an install URL.
versioning and compatibility
API version 1 is selected by /api/bots/v1 and the gateway ready frame. nonbreaking additive fields may appear; clients ignore unknown response fields and event types. requests reject unknown fields. removing fields, changing grant semantics or expanding administrator requires a new API/catalogue version and migration plan. announce breaking retirement at least 90 days ahead and keep old consent snapshots interpretable. the four quickstart languages call this public contract directly; no official bot SDK is required.