Skip to main content
Two budgets apply to every request: Both budgets are token buckets that refill continuously, so a client doesn’t have to wait for a new minute to start before it can send more requests.

​
The headers

Once Usertick has accepted the credential, every HTTP response reports both budgets. A 401 carries none of these headers, and neither does a 429 from the limit per address. A 429 for the credential’s own budget carries only the credential’s headers, because the organization’s budget isn’t checked for that request. GET /me returns the two limits as well, under rateLimits.

​
Handle a 429

A request over a budget returns 429 with a Retry-After header that gives the seconds to wait before retrying. Usertick didn’t run the request, so retrying it is safe.
Calls that return 429 appear as Rate limited (429) in the key’s usage under Settings → Developers → API keys.

​
The limit per address

Before any credential is checked, a high limit of 3,000 requests per minute applies per IP address. It exists only to stop abuse. A request over it returns 429 with GEN-429-001 and a Retry-After header.

​
Other limits

  • Request size. A request body over 64 KB returns 413 with GEN-000-413.
  • Page size. A list returns at most 100 items per page. See Pagination.
  • Subscriptions. A credential and an organization can each hold 100 active webhook subscriptions. Subscriptions that ended don’t count. A subscription over either limit returns 409 with WH-005-008.
  • Webhooks in Settings. An organization can have 100 webhooks under Settings → Developers → Webhooks, turned on or off. Subscriptions don’t count toward this limit. Adding one more in the dashboard fails with 403 and WH-005-009.

​
Stay under the limits

  • Webhooks for new responses. A webhook sends each response as it arrives and uses no API requests.
  • Syncs with updatedSince. A sync that asks only for what changed since the last run reads far less than one that reads everything again. See Keep a copy in sync.
  • Large pages. limit=100 reads four times as much per request as the default.
  • Backoff on 429. A client that waits for Retry-After recovers sooner than a tight retry loop, which only spends the next requests faster.