Rate Limits

Overview

The Nouvel API enforces rate limits to ensure fair usage and system stability. All API keys are subject to a 60 requests per minute limit, regardless of your plan tier.

Rate limits are enforced at the infrastructure level, ensuring consistent and reliable limiting across all API endpoints.

Rate Limit Details

number

default:"60"

Maximum number of requests allowed per minute per API key

string

default:"1 minute"

Time window for rate limit calculations (sliding window)

string

default:"per-key"

Rate limits are applied per API key, not per user or organization

Rate Limit Headers

Every API response includes standard rate limit headers to help you track your usage:

Header	Description	Example
`X-RateLimit-Limit`	Maximum requests allowed in the current window	`60`
`X-RateLimit-Remaining`	Number of requests remaining in the current window	`42`
`X-RateLimit-Reset`	Unix timestamp when the rate limit window resets	`1678901234`

HTTP/1.1 200 OK
X-RateLimit-Limit: 60
X-RateLimit-Remaining: 42
X-RateLimit-Reset: 1678901234
Content-Type: application/json

When You Exceed the Limit

When you exceed the rate limit, the API returns a 429 Too Many Requests status code:

{
  "error": "Rate limit exceeded",
  "reason": "You have made too many requests. Please wait before trying again.",
  "retryAfter": 23
}

When you receive a 429 response, your request is not processed. You must retry the request after the rate limit window resets.

The response includes:

error: Error message indicating rate limit exceeded
reason: Human-readable explanation
retryAfter: Seconds until you can retry (optional)

Additionally, a Retry-After header indicates how many seconds to wait before retrying.

Endpoint Resource Costs

While all endpoints share the same 60 requests/minute limit, they consume different amounts of system resources:

Video Generation (POST /api/v1/generate)

High resource cost - Triggers AI models, video rendering, and long-running background jobs. Each generation uses significant compute resources.

Status Polling (GET /api/v1/jobs/:id)

Low resource cost - Simple database lookup. You can poll frequently within your rate limit.

Project Listing (GET /api/v1/projects)

Low resource cost - Database query with pagination. Efficient for monitoring multiple jobs.

Even though video generation is resource-intensive, the rate limit is the same for all endpoints. Plan your API usage accordingly to balance generation requests with status checks.

Best Practices

1. Implement Exponential Backoff

When you receive a 429 error, implement exponential backoff to avoid repeatedly hitting the rate limit:

async function generateWithBackoff(url: string, maxRetries = 3) {
  let attempt = 0;

  while (attempt < maxRetries) {
    try {
      const response = await fetch('https://app.nouvel.ai/api/v1/generate', {
        method: 'POST',
        headers: {
          'Authorization': 'Bearer nvl_...',
          'Content-Type': 'application/json'
        },
        body: JSON.stringify({ urls: [url] })
      });

      if (response.status === 429) {
        const backoffMs = Math.pow(2, attempt) * 1000; // 1s, 2s, 4s...
        console.log(`Rate limited. Retrying in ${backoffMs}ms...`);
        await new Promise(resolve => setTimeout(resolve, backoffMs));
        attempt++;
        continue;
      }

      return await response.json();
    } catch (error) {
      throw error;
    }
  }

  throw new Error('Max retries exceeded');
}

import time
import requests

def generate_with_backoff(url, max_retries=3):
    attempt = 0

    while attempt < max_retries:
        response = requests.post(
            'https://app.nouvel.ai/api/v1/generate',
            headers={
                'Authorization': 'Bearer nvl_...',
                'Content-Type': 'application/json'
            },
            json={'urls': [url]}
        )

        if response.status_code == 429:
            backoff_s = 2 ** attempt  # 1s, 2s, 4s...
            print(f'Rate limited. Retrying in {backoff_s}s...')
            time.sleep(backoff_s)
            attempt += 1
            continue

        return response.json()

    raise Exception('Max retries exceeded')

2. Cache Responses

Avoid unnecessary API calls by caching responses that don’t change frequently:

Cache completed project data (projects in completed or failed status won’t change)
Store project metadata locally after the initial fetch
Use ETags or Last-Modified headers when available (future enhancement)

3. Batch Operations

When checking status for multiple jobs, use the list endpoint instead of individual status checks:

// Single request to check multiple jobs
const projects = await fetch('https://app.nouvel.ai/api/v1/projects?limit=50', {
  headers: { 'Authorization': 'Bearer nvl_...' }
});

// 10 requests for 10 jobs
for (const jobId of jobIds) {
  await fetch(`https://app.nouvel.ai/api/v1/jobs/${jobId}`, {
    headers: { 'Authorization': 'Bearer nvl_...' }
  });
}

4. Smart Polling Intervals

Adjust your polling frequency based on the project status:

Generating status: Poll every 15-30 seconds
Post-processing status: Poll every 10-15 seconds
Completed/failed status: Stop polling (cache the result)

async function pollUntilComplete(jobId: string) {
  let status = 'generating';

  while (status !== 'completed' && status !== 'failed') {
    const job = await fetch(`https://app.nouvel.ai/api/v1/jobs/${jobId}`, {
      headers: { 'Authorization': 'Bearer nvl_...' }
    }).then(r => r.json());

    status = job.status;

    // Adaptive interval based on status
    const interval = status === 'generating' ? 30000 : 15000;
    await new Promise(resolve => setTimeout(resolve, interval));
  }

  return job;
}

5. Monitor Rate Limit Headers

Track your rate limit usage to avoid hitting the limit:

const response = await fetch('https://app.nouvel.ai/api/v1/generate', {
  method: 'POST',
  headers: {
    'Authorization': 'Bearer nvl_...',
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({ urls: [productUrl] })
});

const remaining = parseInt(response.headers.get('X-RateLimit-Remaining') || '0');
const reset = parseInt(response.headers.get('X-RateLimit-Reset') || '0');

if (remaining < 10) {
  console.warn(`Only ${remaining} requests remaining. Reset at ${new Date(reset * 1000)}`);
}

Webhook Delivery

Webhook deliveries do not count toward your rate limit. Webhooks are initiated by Nouvel’s servers, not your API key, and are not subject to the 60/minute restriction.

When you register a webhookUrl with your generation request, Nouvel will POST to your URL when the job reaches a terminal state. These outbound deliveries are separate from your rate-limited API calls. See the Webhooks guide for full details.

Concurrent Video Generation

In addition to the 60 requests/minute API rate limit, video generation has its own concurrency limits based on your plan:

Plan	Videos/Month	Max Concurrent Jobs
Scale	30	3
Business	120	10

Concurrent jobs are counted per organization. If you submit more jobs than your concurrency limit allows, excess requests will be queued and processed as slots become available.

Need Higher Limits?

If your use case requires higher rate limits or concurrency, please contact our team at support@nouvel.ai. Enterprise plans with custom limits are available.

Most integrations work comfortably within the 60/minute API rate limit by following the best practices above. Since video generation takes 2–5 minutes per job, use webhooks or poll job status rather than blocking on the response.

Getting Started

Core Concepts

Video Generation

Projects

Publishing

Analytics

AI Copilot

Overview

Rate Limit Details

Rate Limit Headers

When You Exceed the Limit

Endpoint Resource Costs

Video Generation (POST /api/v1/generate)

Status Polling (GET /api/v1/jobs/:id)

Project Listing (GET /api/v1/projects)

Best Practices

1. Implement Exponential Backoff

2. Cache Responses

3. Batch Operations

4. Smart Polling Intervals

5. Monitor Rate Limit Headers

Webhook Delivery

Concurrent Video Generation

Need Higher Limits?

​Overview

​Rate Limit Details

​Rate Limit Headers

​When You Exceed the Limit

​Endpoint Resource Costs

Video Generation (POST /api/v1/generate)

Status Polling (GET /api/v1/jobs/:id)

Project Listing (GET /api/v1/projects)

​Best Practices

​1. Implement Exponential Backoff

​2. Cache Responses

​3. Batch Operations

​4. Smart Polling Intervals

​5. Monitor Rate Limit Headers

​Webhook Delivery

​Concurrent Video Generation

​Need Higher Limits?

Overview

Rate Limit Details

Rate Limit Headers

When You Exceed the Limit

Endpoint Resource Costs

Best Practices

1. Implement Exponential Backoff

2. Cache Responses

3. Batch Operations

4. Smart Polling Intervals

5. Monitor Rate Limit Headers

Webhook Delivery

Concurrent Video Generation

Need Higher Limits?