Rate limits

Rate limits protect the platform from overload and are applied per OAuth client, not per user or per account.

Two windows apply simultaneously. Exceeding either returns 429 Too Many Requests.

Every successful response includes your remaining allowance for both windows:

HTTP/1.1 200 OK
remaining_requests_minute: 57
remaining_requests_day: 9863

Poll these rather than counting requests yourself — they are authoritative.

HTTP/1.1 429 Too Many Requests
retry-after: 43
Content-Type: application/json

{
  "message": "Too many requests",
  "available_in_seconds": 43
}

retry-after and available_in_seconds carry the same value: the number of seconds until the exceeded window resets. Wait that long before retrying.

Both fields are computed from the window you actually breached, so a daily-limit breach will return a much larger value than a per-minute one. Do not assume a fixed retry delay.

Limits apply to requests authenticated with an OAuth client-credentials token. Requests made by Rosterfy's own first-party applications — the admin console and the mobile app — are excluded and do not consume your quota.

A few endpoints carry their own limit on top of the per-client windows, because each call is expensive to serve. These are keyed on the resource, not the client, and apply to client-credentials tokens only.

Exceeding one returns the same 429 response as above, with retry-after set to the time until that resource's window resets. Regenerating a report queues a full export, so poll the report's status or set is_scheduled on the report rather than regenerating it to pick up new data.

• Read remaining_requests_minute and back off before you hit zero, rather than treating 429 as your signal.
• On 429, honour retry-after exactly. Retrying sooner consumes another attempt against the window and extends the lockout.
• Use bulk endpoints where they exist. One mass-create call costs a single request; a loop of individual creates costs one each.
• Prefer webhooks over polling. Subscribing to an event costs nothing against your quota; polling a list endpoint every minute costs 1,440 requests a day.