Rate Limits

Moviie applies rate limits to protect service stability and to keep expensive operations bounded. Limits can be scoped by API key, organization, video, playback session, or source address depending on the endpoint.

Default limits

Authenticated REST API traffic is limited per API key:

Some endpoints also have stricter limits because they start generation jobs, create uploads, or perform high-volume search/interactive work. Write operations that create, update, delete, upload, or start generation work can receive stricter per-organization and per-video budgets.

Requests can be denied when any applicable scope exceeds its limit. For example, an organization can remain within the default API-key limit while a single video or generation category is temporarily limited.

Rate limit exceeded

When a limit is exceeded, the API returns:

HTTP/1.1 429 Too Many Requests
Retry-After: 60

{ "error": "rate_limited" }

The Retry-After header is expressed in seconds. Some authentication-level limits may return a different human-readable error string, but clients should treat any 429 response as a rate-limit response and wait for Retry-After before retrying.

Best practices

• Implement exponential backoff when you receive a 429 response. Wait before retrying.
• For batch operations (e.g., fetching analytics for many videos), throttle your requests or batch them where the API supports it.
• Use server-side caching for frequently accessed data (e.g., collection lists) to avoid redundant API calls.
• Avoid immediately retrying generation or upload requests from multiple workers. Queue them client-side and respect the longest Retry-After value you receive.