ConnectCloud Developers

Rate limits

The APIs limit requests with a token bucket per authenticated principal and route: your key's identity (personal key: its owner; service account: the account) and the endpoint template (GET /items/{ref} counts separately from GET /items). Callers behind the same IP address do not share a budget. A limit holds once for the whole platform, however many instances of a module serve your requests.

Scope Sustained Burst
HR, desk, forge and flows routes 20 requests/s 100
Comms routes (per client address, not per principal) 20 requests/s 100
Masterdata AI drafts (…:draft) 1 request every 2 s 20
Masterdata imprint lookup POST /imprint:lookup 1 request every 5 s 10
Key exchange POST /auth/token limited per client address
Comms inbound webhooks POST /hooks/{publicId} 10 requests/s per client address 50
Requests without a valid token limited per client address
Other modules see the module's reference (Conventions)

Desk bulk endpoints accept up to 200 items per request, so a bulk call is almost always better than 200 single calls.

When you exceed a limit

HTTP/1.1 429 Too Many Requests
Retry-After: 2
Content-Type: application/json

{"error": "too many requests", "code": "rate_limited"}

Retry-After is the number of whole seconds until the bucket holds a request again (at least 1): a route with 1 request every 5 s answers up to 5. Wait that long, then continue. Back off exponentially if 429s repeat.

Staying below the limits

  • Cache the access token (one exchange per 15 minutes, not per request).
  • Cache configuration (bootstrap) and refresh it only when you see unknown keys.
  • Use delta sync and webhooks instead of polling.
  • Use bulk endpoints and large pages (limit=500 on desk).
  • Spread batch jobs over time instead of running many requests in parallel.

View as Markdown