Rate Limiting

API request limits and automatic handling by our official SDKs.

📊 Overview

Sharokey implements rate limiting to ensure fair usage and protect our infrastructure. Our SDKs automatically handle all rate limiting scenarios with built-in retry logic and exponential backoff.

Official SDKs:

• CLI C# Tool - Cross-platform command-line interface
• JavaScript SDK - For Node.js and modern web applications
• JavaScript CDN - Simple browser integration
• Python SDK - Async Python client

🚦 Rate Limits by Operation

Authentication Operations

• Limit: 10 requests per minute
• Scope: Per token
• SDK Handling: Automatic retry with exponential backoff

Secrets Management

• Limit: 30 requests per minute
• Scope: Per token
• SDK Handling: Request queuing and intelligent batching

Company Token Operations

• Limit: 5 requests per minute
• Scope: Per token
• SDK Handling: Sequential processing with delays

🛠️ SDK Rate Limit Handling

All our SDKs automatically handle rate limits without any configuration required:

CLI C# Rate Limiting

# The CLI automatically retries when rate limited
sharokey create "content" --hours 24 --views 1
# If rate limited: "Rate limit reached, retrying in 30 seconds..."

# Bulk operations are automatically throttled
sharokey bulk-create secrets.json
# Processes in batches with automatic delays

JavaScript SDK Rate Limiting

// SDK automatically handles rate limits
const client = new SharokeyClient({ token: 'your_token' });

try {
  // This will automatically retry if rate limited
  const secret = await client.createSecret("content", {
    hours: 24, views: 1
  });
  console.log(secret.share_url);
} catch (error) {
  // Rate limit errors are handled automatically
  // Only unrecoverable errors reach this point
  console.error('Failed after retries:', error.message);
}

// Bulk operations with automatic throttling
const secrets = await Promise.all([
  client.createSecret("secret 1", { hours: 24 }),
  client.createSecret("secret 2", { hours: 24 }),
  client.createSecret("secret 3", { hours: 24 })
  // SDK automatically spaces these requests
]);

Python SDK Rate Limiting

import sharokey

client = sharokey.SharokeyClient(token='your_token')

try:
    # Automatic retry and backoff
    secret = await client.create("content", hours=24, views=1)
    print(secret.share_url)
except sharokey.RateLimitError as e:
    # This should rarely happen due to automatic handling
    print(f"Rate limited even after retries: {e}")

# Bulk operations with automatic batching
secrets_data = [
    {"content": "secret 1", "hours": 24},
    {"content": "secret 2", "hours": 24},
    {"content": "secret 3", "hours": 24}
]

# SDK automatically batches and throttles these
secrets = await client.create_batch(secrets_data)

🚨 Rate Limit Responses

When rate limits are exceeded, you'll receive this error format:

{
  "success": false,
  "error": {
    "code": "RATE_LIMIT_EXCEEDED",
    "message": "Too many requests. Please try again later.",
    "details": {
      "retry_after": 30,
      "limit": 30,
      "window": 60,
      "reset_at": "2025-08-11T19:30:00Z"
    }
  }
}

Response Headers:

X-RateLimit-Limit: 30
X-RateLimit-Remaining: 0
X-RateLimit-Reset: 1640995200
Retry-After: 30

⚡ SDK Rate Limiting Features

Automatic Retry Logic

• Exponential backoff: Starts with 1 second, doubles each retry
• Maximum retries: 3 attempts with intelligent retry intervals
• Jitter: Random delays to prevent thundering herd effects

Request Queuing

• Smart batching: Groups multiple requests when possible
• Priority handling: Critical operations get higher priority
• Memory efficient: Minimal memory overhead for queued requests

Monitoring & Metrics

• Rate limit warnings: Proactive notifications when approaching limits
• Request timing: Automatic adjustment based on current usage
• Error tracking: Detailed logging of rate limit encounters

💡 Best Practices with SDKs

High-Volume Operations

CLI C#

# For bulk operations, use built-in batch commands
sharokey bulk-create secrets.json --batch-size 20
# Automatically handles rate limiting

# Monitor progress with verbose output
sharokey create "content" --verbose
# Shows rate limiting status and retry attempts

JavaScript SDK

// Use built-in batch operations for multiple secrets
const secretsData = [/* ... */];
const results = await client.createSecretsBatch(secretsData, {
  batchSize: 20,        // SDK automatically optimizes
  maxConcurrency: 5     // Concurrent requests limit
});

// Enable detailed logging for troubleshooting
const client = new SharokeyClient({ 
  token: 'your_token',
  debug: true  // Shows rate limit handling in logs
});

Python SDK

# Async bulk operations with automatic rate limiting
secrets_data = [/* ... */]
results = await client.create_bulk(secrets_data, 
  batch_size=20,           # Automatic optimization
  max_concurrency=5        # Prevents overwhelming API
)

# Monitor rate limit status
client.enable_rate_limit_logging()  # Detailed rate limit logs
stats = await client.get_rate_limit_status()
print(f"Requests remaining: {stats.remaining}")

Error Handling

All SDKs provide structured error handling for rate limit scenarios:

// JavaScript SDK error handling
try {
  const secret = await client.createSecret("content", options);
} catch (error) {
  if (error instanceof sharokey.RateLimitError) {
    console.log(`Rate limited, retry after: ${error.retryAfter}s`);
    // SDK already retried automatically, this is final failure
  }
}

Configuration Options

// Configure rate limiting behavior
const client = new SharokeyClient({
  token: 'your_token',
  rateLimiting: {
    maxRetries: 5,           // Default: 3
    baseDelay: 2000,         // Default: 1000ms
    maxDelay: 30000,         // Default: 16000ms
    enableJitter: true       // Default: true
  }
});

📊 Monitoring Rate Limits

SDK Rate Limit Status

CLI C#

# Check current rate limit status
sharokey status --rate-limits
# Shows: remaining requests, reset time, current limits

JavaScript SDK

// Get current rate limit information
const status = await client.getRateLimitStatus();
console.log(`Remaining: ${status.remaining}/${status.limit}`);
console.log(`Resets at: ${status.resetAt}`);

Python SDK

# Monitor rate limit usage
status = await client.get_rate_limit_status()
print(f"Remaining: {status.remaining}/{status.limit}")
print(f"Resets in: {status.reset_in_seconds}s")

Performance Optimization

// Optimize for high-volume scenarios
const client = new SharokeyClient({
  token: 'your_token',
  requestQueue: {
    enabled: true,          // Enable request queuing
    maxQueueSize: 1000,     // Queue up to 1000 requests
    processingRate: 25      // Process 25 requests per minute
  }
});

// Use streaming for very large operations
const stream = client.createSecretsStream(secretsData);
stream.on('created', (secret) => {
  console.log(`Created: ${secret.slug}`);
});
stream.on('rateLimited', (delay) => {
  console.log(`Rate limited, waiting ${delay}ms`);
});

🔗 Related Documentation

• Error Handling - Complete error handling reference
• CLI C# Documentation - Command-line rate limiting features
• JavaScript SDK - Browser and Node.js rate limiting
• Python SDK - Async rate limiting patterns
• Authentication - Token management and setup

---

All SDKs implement intelligent rate limiting with automatic retry logic, request queuing, and exponential backoff. No manual rate limit handling required.