Rate Limits

Universal API implements rate limiting to ensure fair usage of the platform and prevent abuse. This document explains the rate limits for different types of users and provides guidance on handling rate limit errors.

Rate Limit Overview

Rate limits vary based on your authentication status:

User Type	Rate Limit	Time Window
Authenticated Users	60 requests	Per minute
Anonymous Users	10 requests	Per 24 hours

How Rate Limiting Works

Universal API uses a sliding window approach to rate limiting:

1. For authenticated users (those providing a valid userId and secretUniversalKey), the system tracks the number of requests made within a 60-second window.
2. For anonymous users (identified by IP address), the system tracks requests over a 24-hour window.

When a user exceeds their rate limit, the API returns a 429 Too Many Requests error with the RATE_LIMIT_EXCEEDED error code.

Rate Limited Endpoints

Rate limiting applies to the following endpoints:

Endpoint	Methods	Description
/action/{actionId}	GET, POST	Executing an action
/action/python/{actionId}	GET, POST	Executing a Python action
/action/python-128mb/{actionId}	GET, POST	Executing a Python action with 128MB memory
/action/nodejs/{actionId}	GET, POST	Executing a Node.js action
/action/python-128mb/inline-code	GET, POST	Executing Python code directly

Other endpoints like /action/list and /action/info/{actionId} are not subject to the same rate limits, but excessive usage may still be throttled.

Credit System for Authenticated Users

In addition to rate limits, authenticated users are subject to a credit system:

1. Each user receives an initial allocation of 100 credits
2. Credits are consumed based on the computing resources used:
   • Minimum of 1 credit per runtime invocation
   • Higher memory allocations consume more credits
   • Longer-running actions consume more credits
3. Credits are automatically replenished monthly if below 100
4. If a user has no credits remaining, they will receive a 402 Payment Required error with the CREDITS_REQUIRED error code

Handling Rate Limit Errors

When you encounter a rate limit error, the API returns a response like:

{
  "success": false,
  "error": {
    "title": "Error",
    "detail": "Daily rate limit exceeded (11/10). Please authenticate for higher limits.",
    "code": "RATE_LIMIT_EXCEEDED",
    "timestamp": "2025-04-06T22:36:00.000Z"
  },
  "meta": {
    "requestId": "req-1234567890",
    "statusCode": 429,
    "timestamp": "2025-04-06T22:36:00.000Z",
    "rateLimitExceeded": "true"
  }
}

Best Practices for Handling Rate Limits

1. Implement exponential backoff: When you receive a rate limit error, wait before retrying, and increase the wait time with each subsequent failure.

2. Authenticate your requests: Anonymous users have much stricter rate limits. Authenticate your requests to get higher limits.

3. Cache responses: For frequently accessed data that doesn't change often, implement client-side caching to reduce the number of API calls.

4. Monitor your usage: Keep track of your API usage to avoid hitting rate limits unexpectedly.

5. Batch requests when possible: Instead of making multiple individual requests, batch them together when the API supports it.

Example: Implementing Exponential Backoff

async function executeActionWithBackoff(actionId, params, retries = 3, baseDelay = 1000) {
  for (let attempt = 0; attempt <= retries; attempt++) {
    try {
      const response = await fetch(`https://api.universalapi.co/action/${actionId}`, {
        method: 'POST',
        headers: {
          'Content-Type': 'application/json',
          'X-Uni-userId': 'your-user-id',
          'X-Uni-secretUniversalKey': 'your-secret-key'
        },
        body: JSON.stringify(params)
      });
      
      const data = await response.json();
      
      if (!data.success) {
        if (data.error.code === 'RATE_LIMIT_EXCEEDED' && attempt < retries) {
          // Calculate delay with exponential backoff and jitter
          const delay = baseDelay * Math.pow(2, attempt) + Math.random() * 1000;
          console.log(`Rate limit exceeded. Retrying in ${delay}ms...`);
          await new Promise(resolve => setTimeout(resolve, delay));
          continue; // Retry after delay
        }
        
        // Handle other errors
        console.error(`Error: ${data.error.detail}`);
        return null;
      }
      
      return data.result;
    } catch (error) {
      console.error('Network error:', error);
      if (attempt < retries) {
        const delay = baseDelay * Math.pow(2, attempt);
        await new Promise(resolve => setTimeout(resolve, delay));
        continue; // Retry after delay
      }
      return null;
    }
  }
  
  return null; // All retries failed
}

Increasing Your Rate Limits

If you need higher rate limits for your application, consider:

1. Authenticating all requests: Always include your userId and secretUniversalKey to get the higher authenticated rate limits.

2. Optimizing your API usage: Review your implementation to ensure you're making efficient use of the API.

3. Contacting support: For enterprise use cases with higher volume requirements, contact Universal API support to discuss custom rate limit options.

Monitoring Your Usage

You can monitor your API usage through the Universal API dashboard or by checking the headers in API responses:

• The /logs/user endpoint provides a history of your API requests
• The response headers include information about your current rate limit status

By staying aware of your usage patterns, you can optimize your implementation to avoid hitting rate limits.