Subscription Bot API Rate Limits
The Telegram subscription bot and Discord subscription bot API uses rate limits to keep integrations responsive. Check the response headers before retrying a throttled request.
Default limits
The default is 60 requests per fixed 60-second window, per HTTP method and route pattern. Buckets are normally scoped to the project. Both the client IP and supplied Bearer token are checked as separate subjects; authenticated requests must fit both limits.
Requests can arrive in a burst. This quota does not require evenly paced one-request-per-second traffic.
Routes can override the default with higher or lower limits. For example, project deletion allows five requests per five minutes. Use the limit documented for the operation you call.
Payment-request creation also applies business limits after authentication: five creation requests per customer per ten-minute window and sixty per project-key actor per ten-minute window. These are separate from the HTTP route limit. The response's error.retry_after_seconds specifies the wait when this check returns 429 TOO_MANY_REQUESTS.
Rate-limit response headers
| Header | Meaning |
|---|---|
X-RateLimit-Limit | Requests allowed in the current window |
X-RateLimit-Remaining | Remaining requests in the current window |
X-RateLimit-Reset | Seconds remaining until the window resets |
Retry-After | Seconds to wait before another attempt after throttling |
Handling throttled requests
Exceeding a limit returns 429. A typical error body is:
{
"ok": false,
"request_id": "44444444-4444-4444-8444-444444444444",
"method": "POST",
"path": "/v2/projects/11111111-1111-4111-8111-111111111111/payment-requests",
"code": 429,
"error": {
"error_code": "TOO_MANY_REQUESTS",
"message": "Too many payment requests in a short period. Please wait before trying again.",
"retry_after_seconds": 60
}
}Wait for the response's Retry-After delay or error.retry_after_seconds, using the longer delay if both are present. If neither is available, use bounded exponential backoff. Keep the original body and idempotency key when retrying writes; a new key represents a new action.
Repeated violations can trigger a temporary ban. By default, ten violations within the configured window cause a 600-second ban. Some routes disable this escalation.
The default limiter fails open if its backing service is unavailable. Selected credential and destructive operations fail closed with 429 instead.
Reduce unnecessary requests
- Cache data when the operation permits it; refresh after relevant changes.
- Use outbound webhook notifications for durable backend event processing.
- Use live updates for subscription bot clients for supported real-time UI events.
- Read the API response and retry conventions before implementing write retries.