> ## 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

<CardGroup cols={3}>
  <Card title="Lightweight" icon="feather">
    **1000 requests/hour** - Languages endpoint - Templates endpoint
  </Card>

  <Card title="Standard" icon="gauge">
    **500 requests/hour** - Project retrieval
  </Card>

  <Card title="Upload" icon="upload">
    **500 requests/hour** - File upload endpoint, Project creation
  </Card>
</CardGroup>

## 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:

<CodeGroup>
  ```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)
  ```
</CodeGroup>

### 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:

<Steps>
  <Step title="Contact Support">
    Reach out to our support team with your use case details
  </Step>

  <Step title="Provide Usage Patterns">
    Share information about your expected request volume and patterns
  </Step>

  <Step title="Review and Approval">
    Our team will review your request and may offer custom rate limits
  </Step>

  <Step title="Enterprise Plans">
    Consider our enterprise plans for guaranteed higher limits
  </Step>
</Steps>

<Card title="Need Higher Limits?" icon="rocket">
  Contact our team at [support@submagic.co](mailto:support@submagic.co) to
  discuss enterprise plans with custom rate limits.
</Card>

{" "}