​
Rate Limits

The Submagic API implements rate limiting to ensure fair usage and maintain service quality for all users. Different endpoints have different rate limits based on their resource intensity.

​
Rate Limit Tiers

Lightweight

1000 requests/hour - Languages endpoint - Templates endpoint

Standard

100 requests/hour - Project retrieval

Upload

30 requests/hour - File upload endpoint, Project creation

​
Rate Limit Headers

Every API response includes rate limit information in the headers: 
HTTP/1.1 200 OK
X-RateLimit-Limit: 30
X-RateLimit-Remaining: 29
X-RateLimit-Reset: 1640995200
HeaderDescription
X-RateLimit-LimitMaximum requests allowed in the current window
X-RateLimit-RemainingRequests remaining in the current window
X-RateLimit-ResetUnix timestamp when the rate limit resets

​
Rate Limit Exceeded

When you exceed the rate limit, you’ll receive a 429 Too Many Requests response: 
{
  "error": "RATE_LIMIT_EXCEEDED",
  "message": "Rate limit exceeded. Please try again later.",
  "retryAfter": 30
}
The response includes:
  • retryAfter: Seconds to wait before making another request
  • Retry-After header: Same information as retryAfter field

​
Best Practices

​
1. Implement Exponential Backoff

When you receive a 429 response, implement exponential backoff: 
async function makeRequestWithRetry(url, options, maxRetries = 3) {
  for (let attempt = 0; attempt < maxRetries; attempt++) {
    try {
      const response = await fetch(url, options);

      if (response.status === 429) {
        const retryAfter = response.headers.get("Retry-After");
        const delay = Math.min(Math.pow(2, attempt) * 1000, 30000);
        await new Promise((resolve) => setTimeout(resolve, delay));
        continue;
      }

      return response;
    } catch (error) {
      if (attempt === maxRetries - 1) throw error;
    }
  }
}

​
2. Monitor Rate Limit Headers

Track your remaining requests to avoid hitting limits: 
const response = await fetch(endpoint, { headers });
const remaining = parseInt(response.headers.get("X-RateLimit-Remaining"));
const resetTime = parseInt(response.headers.get("X-RateLimit-Reset"));

if (remaining < 5) {
  console.log(`Warning: Only ${remaining} requests remaining`);
  console.log(`Rate limit resets at: ${new Date(resetTime * 1000)}`);
}

​
3. Use Webhooks

Instead of polling for status updates, use webhooks to get notified when processing completes: 
{
  "title": "My Video",
  "language": "en",
  "videoUrl": "https://example.com/video.mp4",
  "webhookUrl": "https://yoursite.com/webhook/submagic"
}

​
Rate Limit by Endpoint

EndpointMethodRate Limit
/v1/languagesGET1000/hour
/v1/templatesGET1000/hour
/v1/projects/:idGET100/hour
/v1/projectsPOST30/hour
/v1/projects/uploadPOST30/hour

​
Increasing Rate Limits

If you need higher rate limits for your application:
1

Contact Support

Reach out to our support team with your use case details
2

Provide Usage Patterns

Share information about your expected request volume and patterns
3

Review and Approval

Our team will review your request and may offer custom rate limits
4

Enterprise Plans

Consider our enterprise plans for guaranteed higher limits

Need Higher Limits?

Contact our team at support@submagic.co to discuss enterprise plans with custom rate limits.