Skip to content
tailendAPI
OpenAPIGet an API key

Account

Limits & usage

The per-minute rate limit, the monthly quota, and the headers that report both.

View as Markdown

Two independent limits apply to every key. Both return 429, told apart only by error.code:

LimitScopeOn refusal
Rate limitPer key, per minute429 rate_limited, short Retry-After — wait it out and retry
Monthly quotaPer client, per UTC calendar month, across every key on the account429 quota_exceeded, Retry-After points at the 1st of next month — don't retry sooner

A request refused by either limit isn't billed and doesn't consume the allowance that refused it.

Headers

  • X-RateLimit-Limit / X-RateLimit-Remaining / X-RateLimit-Reset, and the equivalent RateLimit-* trio — the per-minute limit, on every response.
  • X-Quota-Limit / X-Quota-Remaining / X-Quota-Reset — the monthly allowance, only on a plan that has one.
  • Retry-After — seconds to wait, sent on both 429s and on 503.

See the API reference for the headers on each response.

Access

Every endpoint and include= add-on shows its access requirement in the endpoint reference. include=source requires an entitled key: without one you get 403 include_not_permitted, unless you add include_mode=lenient — see Shaping responses.

What to do

  • Branch on error.code, not on the 429 status alone — the two limits need different responses.
  • Read X-RateLimit-Remaining before you burst a batch of requests, and back off before you hit zero rather than after.
  • A 304 still counts as a request against both limits.