Skip to main content

Manage rate limiting

Rate limits are an essential aspect of the Nuclia platform, ensuring fair usage and optimal performance for all users interacting with Nuclia APIs. This document outlines the rate limits enforced by Nuclia and provides guidelines for handling rate-limited responses effectively.

Introduction​

Nuclia can apply two types of limits to its APIs:

  • Regular API rate limits: By default, the sum of all authenticated requests in a Nuclia account cannot exceed 2400 requests per minute. Note that this limit can be customized on a per-account basis. Please contact Nuclia's support team if you need an increase.

  • Ingestion back pressure limits: Nuclia implements a back-pressure mechanism to manage ingestion pipeline overload. This mainly affects endpoints for uploading data and creating or updating resources.

Handling Rate-Limited Responses​

Nuclia adheres to the HTTP standard and will return a response with a 429 status codes when the limits are exceeded.

The official Nuclia API clients already have built-in mechanisms for retrying requests when rate limits are encountered:

However, if you are interacting directly with the API, we recommend using an exponential backoff retry strategy when limits are reached.

When ingestion back pressure rate limits are hit, the response will include a try_after key with an estimated UTC time for retrying the request. You can use this value for retry logic as an alternative to the exponential backoff strategy.

Example 1: Regular API rate limits​

Here's an example of how to implement an exponential backoff retry strategy in Python:

import time
import requests

def make_request_with_exponential_backoff(url, headers, max_retries=5):
    retries = 0
    while retries < max_retries:
        response = requests.get(url, headers=headers)
        if response.status_code == 200:
            return response.json()
        elif response.status_code == 429:
            wait_time = 2 ** retries  # Exponential backoff: 2^retries
            print(f"Rate limit exceeded. Retrying in {wait_time} seconds...")
            time.sleep(wait_time)
            retries += 1
        else:
            response.raise_for_status()
    raise Exception("Max retries exceeded")

# Example usage
url = "https://api.nuclia.com/your-endpoint"
headers = {"Authorization": "Bearer YOUR_ACCESS_TOKEN"}
data = make_request_with_exponential_backoff(url, headers)
print(data)

Example 2: Ingestion back pressure limits​

Here's an example of how to use the try_after key from the response to manage rate limits:

import time
from datetime import datetime

import requests


def make_request_with_try_after_info(url, headers, max_retries=5):
    retries = 0
    while retries < max_retries:
        response = requests.get(url, headers=headers)
        response_body = response.json()
        if response.status_code == 200:
            return response.json()
        elif response.status_code == 429 and "try_after" in response_body:
            try_after = response_body["try_after"]
            retry_time = datetime.strptime(try_after, "%Y-%m-%dT%H:%M:%S.%fZ")
            wait_time = (retry_time - datetime.utcnow()).total_seconds()
            print(
                f"Rate limit exceeded. Retrying at {retry_time} (in {wait_time} seconds)..."
            )
            time.sleep(wait_time)
            retries += 1
        else:
            response.raise_for_status()
    raise Exception("Max retries exceeded")


# Example usage
url = "https://api.nuclia.com/your-endpoint"
headers = {"Authorization": "Bearer YOUR_ACCESS_TOKEN"}
data = make_request_with_try_after_info(url, headers)
print(data)

These examples demonstrate how to handle rate limits effectively, ensuring that your application respects the limits and retries appropriately.