Rate Limits and Quota System

The NordStellar Dark Web API implements a comprehensive rate limiting and quota system to ensure fair usage, maintain service performance, and prevent abuse. Understanding these limits is essential for designing efficient integrations and avoiding service disruptions.

Understanding the Difference

Before diving into specifics, it's important to understand the difference between rate limits and quotas:

• Rate Limits: Short-term restrictions on how many requests you can make in a brief time window (per second/minute)
• Quotas: Long-term restrictions on total usage over an extended period (typically monthly)

Rate Limits

Rate limits control how frequently you can make requests to the API in short time windows. These limits vary by endpoint based on the computational intensity of the operation.

Endpoint-Specific Rate Limits

Different endpoints have different rate limits based on their resource requirements:

Rate Limit Headers

Every API response includes headers that provide information about your current rate limit status:

X-RateLimit-Limit: 200
X-RateLimit-Remaining: 195
X-RateLimit-Reset: 2023-12-01T12:00:30Z

• X-RateLimit-Limit: The maximum number of requests allowed in the current time window
• X-RateLimit-Remaining: The number of requests remaining in the current time window
• X-RateLimit-Reset: When the rate limit counter will reset

Handling Rate Limit Errors

If you exceed your rate limit, the API will respond with a 429 Too Many Requests status code. Your application should:

1. Capture the rate limit error
2. Extract the X-RateLimit-Reset timestamp from the response
3. Pause requests until after the reset time
4. Implement exponential backoff for retries

Quota System

While rate limits control short-term request patterns, the quota system governs your total API usage over your billing period.

Quota Allocation

Quotas are allocated based on your subscription tier and are typically reset monthly. Your quota determines the total number of requests you can make during this period, regardless of rate limits.

Quota Headers

API responses include headers that provide information about your current quota status:

X-Quota-Limit: 100000
X-Quota-Remaining: 87342
X-Quota-Reset: 2023-12-31T23:59:59Z

• X-Quota-Limit: Your total quota for the current period
• X-Quota-Remaining: The number of requests remaining in your quota
• X-Quota-Reset: When your quota will reset

Quota Exhaustion

If you exhaust your quota, the API will respond with a 402 Payment Required status code. At this point, you have two options:

1. Wait until your quota resets at the beginning of the next billing period
2. Contact your account manager to discuss increasing your quota allocation

Best Practices for Managing Limits

To make the most efficient use of your rate limits and quotas:

Efficient Request Design

• Use bulk operations when possible instead of individual lookups
• Cache API responses for frequently accessed data
• Implement client-side rate limiting to stay within server limits

Request Distribution

• Distribute requests evenly over time rather than sending in bursts
• Schedule batch operations during off-peak hours
• Use queuing systems for large-scale operations

Monitoring and Alerting

• Track your quota usage and set up alerts as you approach limits
• Monitor rate limit errors and adjust request patterns accordingly
• Analyze usage patterns to optimize API integration

Quota Planning

• Forecast your API usage needs for proper quota allocation
• Build in a safety buffer for unexpected usage spikes
• Consider distribution across different environments (dev, staging, production)

Limit Increases

If you find that the standard rate limits or quotas are insufficient for your use case:

1. Analyze your current usage patterns to identify optimization opportunities
2. Document your specific needs and use cases
3. Contact your account manager to discuss limit adjustments

Your account manager can work with you to find the right balance of limits for your specific integration needs while ensuring fair system usage across all customers.

Common Scenarios and Solutions

By understanding and working within the rate limit and quota system, you can build reliable and efficient integrations with the NordStellar Dark Web API.