Tellagen
API ReferenceRate limits
All documentation

Search all guides and API reference text. Method and scope filter endpoints only.

Rate limits

Tellagen limits API requests to protect service availability. These limits apply across endpoints.

Default limits

Each traffic class has a short and a long window. An authenticated browser request also uses a user limit.

Default limits
Traffic and scopePast 1 secondLong window
API keys on Free20 requests600 requests in the past 60 seconds
API keys on Team100 requests3,000 requests in the past 60 seconds
Browser user within company100 requestsNo user-specific long window
Browser company500 requests5,000 requests in the past 10 seconds
Anonymous client IP20 requests200 requests in the past 10 seconds

How requests share the limits

API keys for one company share an API allowance. Team has five times the Free API allowance.

Each browser user in a company has a separate 100-request allowance per second. All tabs and sessions for that user share it.

A different user gets a separate user allowance but shares the company limits.

Every browser request must fit the user limit and both company windows.

API keys do not use the browser-user limit. Anonymous requests do not use it either.

API requests do not consume browser user or company allowances.

Browser company means the sum of user traffic for one company.

Each client IP has a separate anonymous allowance. Anonymous traffic does not use company or user allowances.

The rate limiter counts each request that it accepts. An endpoint error does not remove it from that count.

The rate limiter does not count a request that it rejects. It does not extend the wait.

How sliding windows work

Tellagen counts requests in a sliding window. Each request must fit every limit for its traffic class.

For API traffic, each request counts for one second in the short window and 60 seconds in the long window.

For browser traffic, each request counts for one second in the short window and 10 seconds in the long window.

For browser users, each request counts for one second in the user window. The user limit has no long window.

Each browser request counts in the user window and both browser-company windows.

Earlier requests leave each window as they reach those ages. The allowance does not reset at the start of a second or minute.

For example, 20 Free API requests arrive at 12:00:00.900. Another request at 12:00:01.000 still exceeds the one-second limit.

Those 20 requests leave the one-second window at 12:00:01.900. They still count toward the 60-second limit.

Response headers

The API returns these headers for requests subject to the rate limits:

Response headers
HeaderMeaning
X-RateLimit-LimitThe smallest configured limit across all applicable windows. Free API traffic is 20. Team API traffic is 100. Browser-user traffic is 100.
X-RateLimit-RemainingThe smallest number of requests still available across all applicable windows. The value cannot be less than zero.
Retry-AfterThe wait time rounded up to whole seconds, with a minimum of one second. The API includes this header in a rate limit response (HTTP 429).
Rate-Limit-PolicyThe limits and window lengths that apply to the request. For example, 100;w=1, 500;w=1, 5000;w=10 describes a browser user and company.

If a request exceeds a limit

The API returns HTTP 429 with the error code rate_limited. The error details include retry_after_seconds, which matches the Retry-After header.

If several windows are full, Retry-After uses the longest wait. Concurrent requests can use capacity before your retry arrives.

  1. Wait at least the number of seconds in Retry-After before another attempt.
  2. If another attempt returns HTTP 429, wait for the new Retry-After value.
  3. Set a maximum number of attempts in your client.
  4. Spread requests across time to reduce bursts.
  5. If several workers share a company, add a small random delay after the required wait.

Changes to limits

These values are the current defaults. Tellagen can change these limits over time or set different limits for individual companies.

For example, we can adjust limits to protect service availability or respond to unusual API use.