Skip to main content
The LiveAvatar API enforces per-caller rate limits on every public endpoint. A caller that exceeds a limit receives a 429 Too Many Requests response and should retry after the interval given in the Retry-After header.

​
How limits are counted

Limits are counted per caller and per endpoint, over a fixed one-second window.
  • Per caller. The caller is identified by the credential on the request: the X-API-KEY header for backend calls, or the Bearer session token for session-scoped calls. Unauthenticated requests are counted by client IP.
  • Per endpoint. Each endpoint has its own counter. Requests to GET /v1/avatars do not consume budget for GET /v1/voices. Path parameters are ignored, so GET /v1/sessions/{session_id} shares one counter across all session IDs.
  • Fixed window. The counter resets at the start of each one-second window. The X-RateLimit-Reset header reports the seconds remaining in the current window.
Because the identity is the API key rather than the account, two API keys in the same space have independent budgets.

​
Limits by endpoint

Session lifecycle calls are counted per session token, so each active session has its own budget. A backend that manages many concurrent sessions is not throttled by their combined keep-alive traffic.

​
Response headers

Every rate-limited endpoint returns these headers on both successful and rejected responses: A rejected request also includes:

​
Rejected requests

An over-limit request returns HTTP 429 with the standard error envelope:
The request is rejected before any processing, so a rejected call has no side effects.

​
Handling limits

  • Honor Retry-After. Windows are one second, so the wait is never longer than that. Retry after the given interval rather than immediately.
  • Watch X-RateLimit-Remaining. When it reaches zero, pause until the window resets instead of sending a request that will be rejected.
  • Spread bursts. Limits cap requests per second, not per minute. Ten calls in one second are rejected; ten calls spread across two seconds are not.
  • Reuse session tokens. Minting a new token for every operation consumes the POST /v1/sessions/token budget. Mint one token per session and reuse it for lifecycle calls.

​
Availability

Rate limiting is designed to fail open. If the limiter itself is unavailable, requests are allowed through rather than rejected, and no 5xx is returned. Rate limit headers are still present on the response.