> ## Documentation Index
> Fetch the complete documentation index at: https://docs.submagic.co/llms.txt
> Use this file to discover all available pages before exploring further.

# Rate Limits

> Understanding Submagic API rate limits and best practices for handling them

# 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

> [card] Lightweight
>
> **1000 requests/hour** - Languages endpoint - Templates endpoint

> [card] Standard
>
> **500 requests/hour** - Project retrieval

> [card] Upload
>
> **500 requests/hour** - File upload endpoint, Project creation

## Rate Limit Headers

Every API response includes rate limit information in the headers:

```http theme={null}
HTTP/1.1 200 OK
X-RateLimit-Limit: 30
X-RateLimit-Remaining: 29
X-RateLimit-Reset: 1640995200
```

| Header | Description |
| - | - |
| `X-RateLimit-Limit` | Maximum requests allowed in the current window |
| `X-RateLimit-Remaining` | Requests remaining in the current window |
| `X-RateLimit-Reset` | Unix timestamp when the rate limit resets |

## Rate Limit Exceeded

When you exceed the rate limit, you'll receive a `429 Too Many Requests` response:

```json theme={null}
{
  "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:

```javascript JavaScript theme={null}
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;
    }
  }
}
```

```python Python theme={null}
import time
import requests
from requests.adapters import HTTPAdapter
from urllib3.util.retry import Retry

def make_request_with_retry(url, headers, max_retries=3):
    session = requests.Session()

    retry_strategy = Retry(
        total=max_retries,
        status_forcelist=[429, 500, 502, 503, 504],
        backoff_factor=1
    )

    adapter = HTTPAdapter(max_retries=retry_strategy)
    session.mount("http://", adapter)
    session.mount("https://", adapter)

    return session.get(url, headers=headers)
```

### 2. Monitor Rate Limit Headers

Track your remaining requests to avoid hitting limits:

```javascript theme={null}
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:

```json theme={null}
{
  "title": "My Video",
  "language": "en",
  "videoUrl": "https://example.com/video.mp4",
  "webhookUrl": "https://yoursite.com/webhook/submagic"
}
```

## Rate Limit by Endpoint

| Endpoint | Method | Rate Limit |
| - | - | - |
| `/v1/languages` | GET | 1000/hour |
| `/v1/templates` | GET | 1000/hour |
| `/v1/projects/:id` | GET | 100/hour |
| `/v1/projects` | POST | 30/hour |
| `/v1/projects/upload` | POST | 30/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

> [card] Need Higher Limits?
>
> Contact our team at [support@submagic.co](mailto:support@submagic.co) to
> discuss enterprise plans with custom rate limits.

&#x20;


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.