Rate Limit Tiers

Rate limits are applied at different scopes depending on the endpoint category and your authentication level. Each tier has an independent counter.

Rate Limit Headers

Every API response includes three headers that tell you exactly where you stand with your current rate limit window.

Example Response Headers

HTTP/1.1 200 OK
Content-Type: application/json
X-RateLimit-Limit: 300
X-RateLimit-Remaining: 247
X-RateLimit-Reset: 1707350460

429 Too Many Requests

When you exceed a rate limit, the API returns a 429 status code with a RATE_LIMITED error. The response includes a Retry-After header indicating how many seconds to wait before sending another request.

{
  "success": false,
  "error": {
    "code": "RATE_LIMITED",
    "message": "Too many requests. Please wait before retrying.",
    "details": {
      "limit": 100,
      "window": "60s",
      "retryAfter": 23,
      "tier": "global"
    }
  }
}

Response Headers on 429

HTTP/1.1 429 Too Many Requests
Content-Type: application/json
Retry-After: 23
X-RateLimit-Limit: 100
X-RateLimit-Remaining: 0
X-RateLimit-Reset: 1707350483

Retry Strategy: Exponential Backoff with Jitter

When you receive a 429 or a transient server error (500, 502, 503), use exponential backoff with random jitter to retry. This prevents all clients from retrying at the exact same instant (the "thundering herd" problem).

Backoff Schedule

Attempt 1:  1s  + jitter(0-500ms)  =  ~1.0s - 1.5s
Attempt 2:  2s  + jitter(0-500ms)  =  ~2.0s - 2.5s
Attempt 3:  4s  + jitter(0-500ms)  =  ~4.0s - 4.5s
Attempt 4:  8s  + jitter(0-500ms)  =  ~8.0s - 8.5s
Attempt 5: 16s  + jitter(0-500ms)  = ~16.0s - 16.5s

Rate Limit Handling Code Examples

Full working examples showing how to detect and gracefully handle rate limits in four languages.

#!/bin/bash
# Rate-limit-aware API caller with exponential backoff

BASE_URL="https://api.orbai.world"
MAX_RETRIES=5

call_api() {
  local method="$1"
  local path="$2"
  local token="$3"

  for attempt in $(seq 0 $MAX_RETRIES); do
    response=$(curl -s -w "\n%{http_code}" \
      -X "$method" "${BASE_URL}${path}" \
      -H "Authorization: Bearer $token" \
      -H "Content-Type: application/json" \
      -D /tmp/headers.txt)

    http_code=$(echo "$response" | tail -n1)
    body=$(echo "$response" | sed '$d')

    if [ "$http_code" -eq 200 ] || [ "$http_code" -eq 201 ]; then
      echo "$body"
      return 0
    fi

    if [ "$http_code" -eq 429 ]; then
      # Read Retry-After header
      retry_after=$(grep -i "Retry-After" /tmp/headers.txt \
        | tr -d '\r' | awk '{print $2}')
      remaining=$(grep -i "X-RateLimit-Remaining" /tmp/headers.txt \
        | tr -d '\r' | awk '{print $2}')

      echo "Rate limited. Remaining: $remaining. Waiting ${retry_after}s..." >&2
      sleep "$retry_after"
      continue
    fi

    if [ "$http_code" -ge 500 ] && [ "$attempt" -lt "$MAX_RETRIES" ]; then
      delay=$(echo "2^$attempt" | bc)
      jitter=$(echo "scale=2; $RANDOM/32768*0.5" | bc)
      wait_time=$(echo "$delay + $jitter" | bc)
      echo "Server error $http_code. Retrying in ${wait_time}s..." >&2
      sleep "$wait_time"
      continue
    fi

    # Non-retryable error
    echo "$body" >&2
    return 1
  done

  echo "Max retries exceeded" >&2
  return 1
}

# Usage
call_api "GET" "/api/v1/users/me" "$ACCESS_TOKEN"

Best Practices

Follow these guidelines to stay well within rate limits and build efficient integrations.

Frequently Asked Questions

What happens if I keep sending requests after a 429?

Clients that repeatedly ignore 429 responses and the Retry-After header may be temporarily blocked at the IP level. Persistent abuse (sustained requests after multiple warnings) can result in a permanent ban of the IP address or API key.

Do rate limits apply to WebSocket connections?

WebSocket connections have their own rate limiting model. Message throughput is limited per connection, but the limits are significantly higher than REST endpoints since there is no per-request overhead. See the WebSocket Guide for details.

Can I request a higher rate limit?

Enterprise customers can request custom rate limits. Contact your account manager or reach out through the support portal to discuss your requirements.

Are rate limits shared across API keys?

No. Each API key (for OrbGuard Labs) and each authenticated user (for OrbNET) has an independent rate limit counter. The Global tier is per IP address and is the only tier shared across all requests from the same origin.