Rate Limits

Understanding API rate limits and how to handle them effectively.

Rate Limits

Type Limit Scope Description
Global 1000 requests per hour Per API key Overall limit for all API endpoints
Chart Upload 100 requests per hour Per repository Limit for chart upload operations
Search 300 requests per hour Per IP address Limit for search operations

Response Headers

Rate limit information is included in the following response headers:

X-RateLimit-Limit
The maximum number of requests allowed in the current time window
Example: 1000
X-RateLimit-Remaining
The number of requests remaining in the current time window
Example: 999
X-RateLimit-Reset
The time when the current rate limit window resets, in Unix epoch seconds
Example: 1621180800

Examples

Check Rate Limit Status

Get current rate limit status

curl -I https://api.helmbay.com/v1/rate-limit \
  -H "Authorization: Bearer your-api-key"

HTTP/1.1 200 OK
X-RateLimit-Limit: 1000
X-RateLimit-Remaining: 999
X-RateLimit-Reset: 1621180800

Handle Rate Limit Exceeded

Example response when rate limit is exceeded

HTTP/1.1 429 Too Many Requests
X-RateLimit-Limit: 1000
X-RateLimit-Remaining: 0
X-RateLimit-Reset: 1621180800
Retry-After: 3600

{
  "error": {
    "code": "rate_limit_exceeded",
    "message": "API rate limit exceeded",
    "retry_after": 3600
  }
}

Best Practices

Implement Retries

Handle rate limits gracefully

  • Use exponential backoff
  • Respect Retry-After header
  • Add jitter to avoid thundering herd
  • Set maximum retry attempts

Optimize Usage

Make efficient use of rate limits

  • Cache responses when possible
  • Batch operations where supported
  • Monitor rate limit headers
  • Use conditional requests

Implementation Examples

// Example rate limit handling in JavaScript
async function makeRequest(url) {
  try {
    const response = await fetch(url, {
      headers: { 'Authorization': `Bearer ${apiKey}` }
    });

    // Check remaining rate limit
    const remaining = response.headers.get('X-RateLimit-Remaining');
    const reset = response.headers.get('X-RateLimit-Reset');

    if (remaining <= 10) {
      console.warn(`Rate limit running low: ${remaining} requests remaining`);
      console.warn(`Resets at: ${new Date(reset * 1000)}`);
    }

    return await response.json();
  } catch (error) {
    if (error.status === 429) {
      const retryAfter = error.headers.get('Retry-After');
      console.warn(`Rate limit exceeded. Retry after ${retryAfter} seconds`);
      // Implement retry logic here
    }
    throw error;
  }
}

Next Steps

Learn how to integrate rate limit handling in your CI/CD pipeline.

CI/CD Integration Guide →