Skip to main content

Rate limits

Every operation is rate limited. Limits are counted per account (all APP Keys and console sessions of the account share one budget), in a per-second and a per-minute window. The exact numbers for an operation are on its page under Restrictions. Default limits per account: Some operations have tighter limits, for example exports and heavy analytics queries; their Restrictions table shows the actual values.

When you hit a limit

The request fails with HTTP 429 and error code RequestTooFrequently. The response carries the header Flashcat-Request-Rate-Limit-Delay, the number of seconds until the current window resets. Wait at least that long before retrying; if the header is absent, back off exponentially (1 s, 2 s, 4 s, …).
Retrying immediately in a loop keeps the window saturated. Spread bulk jobs over time, and prefer list operations that accept multiple IDs over one call per object.

Permission checks

  • An APP Key with All permissions has no additional API-scope restriction, but remains limited by the creator’s current role permissions.
  • An APP Key with Custom permissions can call only the APIs in its selected scope.
  • A call outside either the key’s scope or the creator’s role permissions fails with HTTP 403 and AccessDenied. The required permission of each operation is listed under Restrictions on its page.
  • Some operations additionally check object-level access (for example, only members of a channel’s team can change it); those rules are described in each operation’s Usage section.
  • Create separate APP Keys for different purposes, each with the smallest scope it needs.

Error codes

Every failure returns the envelope { "request_id": "…", "error": { "code": "…", "message": "…" } }. Branch on error.code; it is stable. message is localized and may change. Other values of the ErrorCode enum in the API reference (RequestVerifyRequired, DangerousOperation, RequestLocked, BalanceNotEnough, UndonedOrderExist) belong to console-only flows such as MFA and billing and are not returned by Open API operations.

Retry advice

  • Retry only 429, 500, 503, and network errors, with exponential backoff (start at 1 second, at most 3 retries). For 429, honor Flashcat-Request-Rate-Limit-Delay.
  • Do not retry other 4xx errors unchanged; they will fail the same way.
  • Treat creates as not idempotent. Before retrying a create that timed out, list or query to check whether the first attempt succeeded.
  • Log the request_id of every failed call; support needs it to locate the request.