TMA CloudTMA Cloud
Reference

Rate Limits

Every request limit the TMA Cloud API applies, and what a refused request looks like.

Every request limit the TMA Cloud API applies, and what a refused request looks like.

Rate Limit Configuration

Each limiter counts requests per IP address, per user, or both, in a fixed window. Counters live in the memory of each server process.

Behind a reverse proxy: add every proxy under Settings → Administration → Known proxies and restart the server. If the connecting proxy is not trusted, every request looks like it came from that proxy and all users share one bucket. See Known Proxies. Sub-users count separately from their account owner, since keys use the individual login.

Endpoint Limits

Authentication Limiter

  • Limit: 25 requests per 15 minutes per IP/email combination.
  • Endpoints:
    • POST /api/login
    • POST /api/signup
    • POST /api/change-password

Failed Login Limiters

Two more limits apply to POST /api/login and count only failed attempts (any response with status 400 or above). A successful login does not use up the allowance.

  • Per IP: 100 failed logins per 15 minutes from one IP address, across all emails. Limits one client trying many accounts.
  • Per account: 20 failed logins per 15 minutes for one email, across all IP addresses. Limits many clients trying one account.

A login that requires MFA and is sent without a code returns 400 MFA code required, which counts as one failure.

The per-account limit applies to anyone who knows the email, so repeated failed attempts can block that account's password login for up to 15 minutes.

General API Limiter

  • Limit: 30,000 requests per 15 minutes per signed-in user; 10,000 per 15 minutes per IP address for requests without a session.
  • Why per user: Keying on the user means colleagues sharing an office IP do not share a bucket. A desktop app keeping a large drive in sync, or copying a folder of thousands of files into Cloud Drive, legitimately makes many requests, so signed-in users get the larger budget.
  • Not counted: the live event stream, GET /api/files/events. It is one long request with its own cap per user, and cutting it would leave apps unaware of changes.
  • Refusals are heard: a refused request's body (an upload's, mostly) is read, up to 32 MB within 30 seconds, before the 429 is sent. A client sends the whole body before it reads the reply, so answering mid-body made it report the server unreachable instead.
  • Endpoints:
    • Public endpoints (e.g. GET /api/signup-status).
    • Authenticated auth and profile endpoints (e.g. /api/profile, /api/sessions, /api/sessions/heartbeat, /api/sessions/offline, /api/mfa/*, /api/logout).
    • All file operation endpoints under /api/files/.
    • All user management endpoints under /api/user/ (including GET /api/user/signup-status).
    • All version check endpoints under /api/version/.
    • OnlyOffice configuration, viewer, and file-serving endpoints under /api/onlyoffice/.
    • All public share link endpoints under /s/.

There is no share-specific limiter. Routes under /s/ use the General API Limiter above.

  • Limit: 10,000 requests per 15 minutes. Share links are unauthenticated, so the key is the IP address.
  • Endpoints: All endpoints under /s/.

Because share links are the only routes reachable without a session, this budget is the one most exposed to anonymous traffic. If you publish links widely, put a lower limit in front of /s/ at your reverse proxy.

Upload Limiter

  • Limit: 20,000 uploads per 30 minutes per user (or per IP if unauthenticated).
  • Endpoints:
    • POST /api/files/upload
    • POST /api/files/upload/bulk
    • POST /api/files/upload/check
    • POST /api/files/:id/replace
    • POST /api/files/:id/derived

Specialized MFA Limiters

  • MFA Verification/Disabling: 5 attempts per minute, keyed on IP + user ID. The limit is this tight because each attempt runs a bcrypt comparison, which is deliberately expensive.
    • POST /api/mfa/verify
    • POST /api/mfa/disable
  • Backup Code Regeneration: 3 attempts per 10 minutes, keyed on IP + user ID.
    • POST /api/mfa/backup-codes/regenerate

Storage Connection Limiter

  • Limit: 20 requests per 15 minutes per user.
  • Purpose: Each request makes outbound requests to an admin-supplied storage endpoint, so it has its own budget below the general limit. Applied in addition to the General API Limiter.
  • Endpoints:
    • PUT /api/user/storage-config
    • POST /api/user/storage-config/test
  • Error: Too many storage connection attempts, please try again later

SSE Connection Limiter

  • Limit: 20 concurrent Server-Sent Events connections per user.
  • Endpoint: GET /api/files/events

Rate Limit Headers

A refused (429) response carries these headers:

  • RateLimit-Limit: The number of requests the window allows
  • RateLimit-Remaining: Always 0
  • RateLimit-Reset: Seconds until the window resets
  • Retry-After: The same number of seconds

Rate Limit Errors

When a rate limit is exceeded:

Status Code: 429 Too Many Requests

Response:

{
  "message": "Too many requests, please try again later",
  "error": "Too many requests, please try again later"
}

The sentence is in both fields; error is not a code here. The failed login limiters use their own sentences: Too many failed sign-in attempts from this network, please try again later (per IP) and Too many failed sign-in attempts for this account, please try again later (per account).

The backup-code cooldown is separate from the limiter above it and answers in the normal shape, with the remaining wait included:

{
  "message": "Please wait 3 minutes and 45 seconds before regenerating backup codes again",
  "retryAfterMs": 225000
}

A regeneration request therefore hits 429 for either of two reasons: the 3-per-10-minutes limiter, or the 5-minute cooldown between successful regenerations.

Handling a 429

  • Wait for the number of seconds in Retry-After before trying again
  • Upload and download many files with the bulk endpoints, and send several ids in one move, copy, delete or share request instead of one request per file

Last updated on

Error Codes

Every machine-readable error code the TMA Cloud API returns.

CLI Commands

Command-line interface commands for TMA Cloud.

On this page

Rate Limit ConfigurationEndpoint LimitsAuthentication LimiterFailed Login LimitersGeneral API LimiterPublic Share LinksUpload LimiterSpecialized MFA LimitersStorage Connection LimiterSSE Connection LimiterRate Limit HeadersRate Limit ErrorsHandling a 429Related Topics