رده‌های سقف نرخ

سقف‌های نرخ بسته به ردهٔ نقطهٔ پایانی و سطح احراز هویت شما در دامنه‌های گوناگون اعمال می‌شوند. هر رده شمارندهٔ مستقل خود را دارد.

سرآیندهای سقف نرخ

هر پاسخ API سه سرآیند دارد که دقیقاً می‌گویند در پنجرهٔ کنونی سقف نرخ کجا ایستاده‌اید.

نمونهٔ سرآیندهای پاسخ

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

۴۲۹ درخواست‌های بیش‌ازحد

وقتی از سقف نرخ بگذرید، API کد وضعیت 429 را همراه با خطای RATE_LIMITED برمی‌گرداند. پاسخ سرآیند Retry-After را دارد که نشان می‌دهد پیش از فرستادن درخواست دیگر چند ثانیه باید صبر کنید.

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

سرآیندهای پاسخ در ۴۲۹

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

راهبرد تلاش دوباره: عقب‌نشینی نمایی با نوسان تصادفی

وقتی 429 یا خطای گذرای سرور (500، 502، 503) می‌گیرید، برای تلاش دوباره از عقب‌نشینی نمایی با نوسان تصادفی استفاده کنید. این کار جلوی تلاش هم‌زمان همهٔ کلاینت‌ها در یک لحظه را می‌گیرد (مشکل «هجوم گله‌ای»).

زمان‌بندی عقب‌نشینی

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

نمونه‌های کد رسیدگی به سقف نرخ

نمونه‌های کامل و کارا که نشان می‌دهند چگونه سقف‌های نرخ را در چهار زبان تشخیص دهید و به‌درستی مدیریت کنید.

#!/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"

بهترین شیوه‌ها

این رهنمودها را دنبال کنید تا با خیال راحت زیر سقف نرخ بمانید و یکپارچگی‌های کارآمد بسازید.

پرسش‌های پرتکرار

اگر پس از ۴۲۹ به فرستادن درخواست ادامه دهم چه می‌شود؟

کلاینت‌هایی که پیوسته پاسخ‌های ۴۲۹ و سرآیند Retry-After را نادیده می‌گیرند ممکن است موقتاً در سطح IP مسدود شوند. سوءاستفادهٔ پیوسته (درخواست‌های مداوم پس از چند هشدار) می‌تواند به مسدودسازی دائمی نشانی IP یا کلید API بینجامد.

آیا سقف‌های نرخ بر اتصال‌های WebSocket اعمال می‌شوند؟

اتصال‌های وب‌سوکت مدل محدودسازی نرخ خود را دارند. گذردهی پیام برای هر اتصال محدود است، اما چون سربار درخواست‌به‌درخواست وجود ندارد، سقف‌ها به‌مراتب بالاتر از نقاط پایانی REST هستند. برای جزئیات راهنمای وب‌سوکت را ببینید.

می‌توانم سقف نرخ بالاتری درخواست کنم؟

مشتریان سازمانی می‌توانند سقف نرخ دلخواه درخواست کنند. برای گفت‌وگو دربارهٔ نیازهای خود با مدیر حساب خود تماس بگیرید یا از راه درگاه پشتیبانی با ما در ارتباط باشید.

آیا سقف‌های نرخ میان کلیدهای API مشترک‌اند؟

خیر. هر کلید API (برای OrbGuard Labs) و هر کاربر احراز هویت‌شده (برای OrbNET) شمارندهٔ مستقل سقف نرخ خود را دارد. ردهٔ سراسری برای هر نشانی IP است و تنها رده‌ای است که میان همهٔ درخواست‌های یک مبدأ مشترک می‌ماند.