Rate Limits

Daily quotas, response headers, and how to back off.

Rate Limits

The only rate-limited endpoint today is POST /v1/video/:id/playback-token. The list / get endpoints are not throttled beyond Cloud Run’s edge protection, but please be a good neighbour — they’re cheap to call but not free.

Quota

Tier	Tokens per UTC day per key
Default	1,000
Custom	Set by Ansdev support

The counter is keyed by API key + UTC date and reset at 23:59:59 UTC. There is no per-IP or per-video sub-bucket — one key, one daily budget.

Response headers

Every response from playback-token carries the standard headers:

X-RateLimit-Limit:     1000
X-RateLimit-Remaining: 873
X-RateLimit-Reset:     1779148800

• X-RateLimit-Limit — your daily quota.
• X-RateLimit-Remaining — tokens left in the current window.
• X-RateLimit-Reset — Unix epoch (seconds) when the counter resets.

When you hit the limit, you get HTTP 429:

{
  "success": false,
  "error": {
    "code":    "RATE_LIMIT_EXCEEDED",
    "message": "Daily limit of 1000 playback tokens exceeded.",
    "status":  429
  }
}

Backoff strategy

async function mintTokenWithRetry(videoId: string, apiKey: string) {
  const res = await fetch(
    `https://api.ansdev.cloud/v1/video/${videoId}/playback-token`,
    {
      method:  'POST',
      headers: { 'x-ansdev-key': apiKey, 'Content-Length': '0' },
    },
  );

  if (res.status === 429) {
    const reset = Number(res.headers.get('X-RateLimit-Reset'));
    const waitS = Math.max(0, reset - Math.floor(Date.now() / 1000));
    throw new Error(`Rate-limited. Retry after ${waitS}s.`);
  }
  return (await res.json()).data;
}

Why daily, not per-second?

A playback token is per-view, not per-frame — one token plays the entire video. Throttling per-second adds 99 percentile noise for a metric (concurrent viewers) we don’t actually want to police. A daily budget protects against runaway scripts while leaving real traffic patterns alone.

Need a higher limit? Email [e-mail] with your use case. The cap can be raised per key without a code change.