Rate Limits

Overview

Satsuma implements rate limiting to ensure fair usage and maintain service quality for all users. This guide explains how rate limits work, how to handle them gracefully, and strategies to optimize your API usage.

Rate Limit Structure

Request-based Limits

Rate limits are enforced per API key across different time windows:

Per Second: Short-term burst protection
Per Minute: Medium-term usage smoothing
Per Hour: Long-term quota management
Per Day: Daily usage caps

Tiered Limits by Plan

Free Tier

Requests: 1,000 per month
Rate: 5 requests per second
Burst: 10 requests per 10 seconds
Quota Reset: Monthly on signup date

Developer - $49/month

Requests: 50,000 per month
Rate: 25 requests per second
Burst: 100 requests per 10 seconds
Quota Reset: Monthly on billing date

Business - $199/month

Requests: 500,000 per month
Rate: 100 requests per second
Burst: 500 requests per 10 seconds
Quota Reset: Monthly on billing date

Enterprise - Custom

Requests: Unlimited or custom limit
Rate: Custom rates up to 1,000 RPS
Burst: Negotiated burst capacity
Quota Reset: Configurable

Rate Limit Headers

Every API response includes rate limit information in the headers:

HTTP/1.1 200 OK
X-RateLimit-Limit: 100
X-RateLimit-Remaining: 95  
X-RateLimit-Reset: 1642678800
X-RateLimit-Retry-After: 15

Header Definitions

X-RateLimit-Limit: Maximum requests allowed in current window
X-RateLimit-Remaining: Requests remaining in current window
X-RateLimit-Reset: Unix timestamp when the limit resets
X-RateLimit-Retry-After: Seconds to wait before retrying (429 responses only)

Handling Rate Limit Responses

429 Rate Limit Exceeded

When you exceed rate limits, the API returns a 429 status with details:

{
  "error": {
    "code": "RATE_LIMIT_EXCEEDED",
    "message": "Rate limit exceeded. Please retry after 60 seconds.",
    "limit": 100,
    "remaining": 0,
    "reset": 1642678800,
    "retry_after": 60
  }
}

Implementing Retry Logic

# Basic request with retry logic using curl
curl -w "HTTP %{http_code}\nLimit: %{header_x-ratelimit-limit}\nRemaining: %{header_x-ratelimit-remaining}\nRetry-After: %{header_x-ratelimit-retry-after}\n" \
  -H "Authorization: your-api-key" \
  -H "Content-Type: application/json" \
  https://api.satsuma.ai/v1/products

# Retry with exponential backoff script
#!/bin/bash
max_retries=3
attempt=0

while [ $attempt -le $max_retries ]; do
  response=$(curl -s -w "HTTPSTATUS:%{http_code}" \
    -H "Authorization: your-api-key" \
    https://api.satsuma.ai/v1/products)
  
  http_status=$(echo $response | tr -d '\n' | sed -e 's/.*HTTPSTATUS://')
  
  if [ $http_status -eq 429 ]; then
    if [ $attempt -eq $max_retries ]; then
      echo "Max retry attempts exceeded"
      exit 1
    fi
    
    delay=$((2**attempt))
    echo "Rate limited. Retrying in $delay seconds..."
    sleep $delay
    ((attempt++))
  else
    echo $response | sed -e 's/HTTPSTATUS:.*//g'
    exit 0
  fi
done

Optimization Strategies

Request Batching

Combine multiple operations into single requests when possible:

# Instead of multiple individual requests:
# curl -H "Authorization: your-api-key" https://api.satsuma.ai/v1/products/prod_123
# curl -H "Authorization: your-api-key" https://api.satsuma.ai/v1/products/prod_456
# curl -H "Authorization: your-api-key" https://api.satsuma.ai/v1/products/prod_789

# Use batch endpoint:
curl -X POST \
  -H "Authorization: your-api-key" \
  -H "Content-Type: application/json" \
  -d '{"product_ids": ["prod_123", "prod_456", "prod_789"]}' \
  https://api.satsuma.ai/v1/products/batch

Caching Strategies

Implement intelligent caching to reduce API calls:

# Simple file-based caching with curl
#!/bin/bash
cache_dir="/tmp/satsuma_cache"
mkdir -p "$cache_dir"

get_product_cached() {
  local product_id="$1"
  local cache_file="$cache_dir/product_$product_id"
  local ttl=300  # 5 minutes
  
  # Check if cache exists and is fresh
  if [ -f "$cache_file" ] && [ $(($(date +%s) - $(stat -c %Y "$cache_file"))) -lt $ttl ]; then
    cat "$cache_file"
    return 0
  fi
  
  # Fetch from API and cache
  curl -s -H "Authentication: your-api-key" \
    "https://api.satsuma.ai/v1/products/$product_id" | tee "$cache_file"
}

# Usage
get_product_cached "prod_123"

Connection Pooling

Reuse HTTP connections to reduce overhead:

# curl automatically reuses connections with --keepalive-time
# Use connection pooling with parallel requests
curl --parallel --parallel-max 10 --keepalive-time 60 \
  -H "Authorization: your-api-key" \
  https://api.satsuma.ai/v1/products/[prod_123,prod_456,prod_789]

# For scripts, use curl with connection reuse
export CURL_OPTS="--keepalive-time 60 --max-time 30"
curl $CURL_OPTS -H "Authorization: your-api-key" https://api.satsuma.ai/v1/products

Rate Limit Monitoring

Tracking Usage

Monitor your rate limit usage to avoid surprises:

#!/bin/bash
# Simple rate limit monitoring script
monitor_rate_limits() {
  local log_file="/tmp/rate_limit_monitor.log"
  
  while true; do
    response=$(curl -s -w "LIMIT:%{header_x-ratelimit-limit}|REMAINING:%{header_x-ratelimit-remaining}|RESET:%{header_x-ratelimit-reset}" \
      -H "Authorization: your-api-key" \
      https://api.satsuma.ai/v1/products 2>&1)
    
    limit=$(echo "$response" | grep -o 'LIMIT:[^|]*' | cut -d: -f2)
    remaining=$(echo "$response" | grep -o 'REMAINING:[^|]*' | cut -d: -f2)
    reset=$(echo "$response" | grep -o 'RESET:[^|]*' | cut -d: -f2)
    
    if [ -n "$limit" ] && [ -n "$remaining" ]; then
      usage_percent=$(( (limit - remaining) * 100 / limit ))
      
      echo "$(date): Limit=$limit, Remaining=$remaining, Usage=${usage_percent}%" >> "$log_file"
      
      if [ $usage_percent -gt 80 ]; then
        echo "WARNING: Rate limit usage at ${usage_percent}%"
      fi
    fi
    
    sleep 60
  done
}

Alerting on High Usage

Set up alerts when approaching rate limits:

#!/bin/bash
# Rate limit alerting script
alert_threshold=80
cooldown_seconds=300
last_alert_file="/tmp/last_rate_limit_alert"

check_and_alert() {
  local limit="$1"
  local remaining="$2"
  
  if [ "$limit" -gt 0 ]; then
    local usage_percent=$(( (limit - remaining) * 100 / limit ))
    
    if [ $usage_percent -ge $alert_threshold ]; then
      local now=$(date +%s)
      local last_alert=0
      
      [ -f "$last_alert_file" ] && last_alert=$(cat "$last_alert_file")
      
      if [ $((now - last_alert)) -gt $cooldown_seconds ]; then
        echo "ALERT: Rate limit usage at ${usage_percent}%" | \
          mail -s "Satsuma API Rate Limit Warning" admin@company.com
        
        # Log to syslog
        logger "Rate limit alert: ${usage_percent}% usage, ${remaining}/${limit} remaining"
        
        echo "$now" > "$last_alert_file"
      fi
    fi
  fi
}

# Usage
response=$(curl -s -w "LIMIT:%{header_x-ratelimit-limit}|REMAINING:%{header_x-ratelimit-remaining}" \
  -H "Authorization: your-api-key" https://api.satsuma.ai/v1/products)
limit=$(echo "$response" | grep -o 'LIMIT:[^|]*' | cut -d: -f2)
remaining=$(echo "$response" | grep -o 'REMAINING:[^|]*' | cut -d: -f2)
check_and_alert "$limit" "$remaining"

Plan Management

Upgrading Plans

When you consistently hit rate limits:

Monitor Usage Patterns

Track your API usage over time to understand peak load requirements

Calculate ROI

Compare the cost of API rate limit delays vs. higher plan pricing

Upgrade Plan

Visit the billing section to upgrade

Verify Limits

Test that new limits meet your application’s needs

Custom Enterprise Limits

For high-volume applications, contact our sales team to discuss:

Custom rate limits above standard plans
Burst capacity for traffic spikes
Regional rate limits for global applications
Dedicated infrastructure for consistent performance

Best Practices

Request Timing

Spread requests evenly instead of bursts when possible
Use jitter in retry delays to avoid thundering herd effects
Queue non-urgent requests during high-traffic periods
Implement circuit breakers to prevent cascade failures

Error Handling

Always check rate limit headers before making next request
Implement exponential backoff with a maximum delay
Log rate limit events for monitoring and optimization
Gracefully degrade functionality when limits are reached

Architecture Considerations

Cache frequently accessed data to reduce API calls
Use webhooks instead of polling for real-time updates
Implement request queuing for batch operations
Consider async processing for non-real-time operations

Troubleshooting

Common Rate Limit Issues

Unexpected 429 errors on low usage

Check if you have multiple processes/servers using the same API key
Verify you’re not making concurrent requests that exceed per-second limits
Review your request batching and caching implementation
Check if your plan has sufficient rate limits for your usage pattern

Rate limits reset unexpectedly

Different rate limit windows (per-second, per-minute, per-hour) have different reset times
Monthly quotas reset on your billing date, not calendar month
Upgrading plans may cause immediate limit increases
Contact support if you see inconsistent reset behavior

High latency during rate limiting

Implement proper backoff strategies instead of aggressive retries
Use connection pooling to reduce connection establishment overhead
Consider upgrading to a higher plan for better rate limits
Monitor for server-side rate limiting vs. client-side queuing delays

Rate Limit Debugging

Use these tools to debug rate limit issues:

# Check current rate limit status
curl -I -H "Authorization: your-key" https://api.satsuma.ai/v1/products

# Monitor rate limit headers in real-time
curl -w "Limit: %{header_x-ratelimit-limit}\nRemaining: %{header_x-ratelimit-remaining}\nReset: %{header_x-ratelimit-reset}\nRetry-After: %{header_x-ratelimit-retry-after}\n" \
  -H "Authorization: your-key" \
  https://api.satsuma.ai/v1/products

# Debug rate limiting with verbose output
curl -v -H "Authorization: your-key" https://api.satsuma.ai/v1/products 2>&1 | \
  grep -E "(X-RateLimit|HTTP/)"

Getting Help

For rate limit assistance:

Review your usage in the dashboard analytics
Check our status page for any rate limiting incidents
Contact support@satsuma.ai with your API key prefix and usage details
For plan upgrades or custom limits, reach out to sales@satsuma.ai

Getting Started

Integration Guide

Overview

Rate Limit Structure

Request-based Limits

Tiered Limits by Plan

Rate Limit Headers

Header Definitions

Handling Rate Limit Responses

429 Rate Limit Exceeded

Implementing Retry Logic

Optimization Strategies

Request Batching

Caching Strategies

Connection Pooling

Rate Limit Monitoring

Tracking Usage

Alerting on High Usage

Plan Management

Upgrading Plans

Custom Enterprise Limits

Best Practices

Request Timing

Error Handling

Architecture Considerations

Troubleshooting

Common Rate Limit Issues

Rate Limit Debugging

Getting Help

Getting Started

Integration Guide

Documentation Index

​Overview

​Rate Limit Structure

​Request-based Limits

​Tiered Limits by Plan

​Rate Limit Headers

​Header Definitions

​Handling Rate Limit Responses

​429 Rate Limit Exceeded

​Implementing Retry Logic

​Optimization Strategies

​Request Batching

​Caching Strategies

​Connection Pooling

​Rate Limit Monitoring

​Tracking Usage

​Alerting on High Usage

​Plan Management

​Upgrading Plans

​Custom Enterprise Limits

​Best Practices

​Request Timing

​Error Handling

​Architecture Considerations

​Troubleshooting

​Common Rate Limit Issues

​Rate Limit Debugging

​Getting Help

Overview

Rate Limit Structure

Request-based Limits

Tiered Limits by Plan

Rate Limit Headers

Header Definitions

Handling Rate Limit Responses

429 Rate Limit Exceeded

Implementing Retry Logic

Optimization Strategies

Request Batching

Caching Strategies

Connection Pooling

Rate Limit Monitoring

Tracking Usage

Alerting on High Usage

Plan Management

Upgrading Plans

Custom Enterprise Limits

Best Practices

Request Timing

Error Handling

Architecture Considerations

Troubleshooting

Common Rate Limit Issues

Rate Limit Debugging

Getting Help