Hız Sınırlama (Rate Limit)

API'yi aşırı yüklenmeye karşı korumak için istek sayısı dakika bazında sınırlanır. Sınır, kayan pencere (sliding window) yöntemiyle hesaplanır.

Her API anahtarının limiti ayrıdır — ortak/global bir limit yoktur. Limit, uç nokta grubuna (kova) göre uygulanır; bir kovadaki tüketim diğerlerini etkilemez.

Kotalar

Kova (bucket)	Varsayılan limit	Kapsam
default	60 istek / dakika	Sipariş, ürün, bakiye, webhook, VNC, erişim bilgileri, yaşam döngüsü (suspend/unsuspend/terminate)
services_read	150 istek / dakika	GET /services, GET /services/{id}
services_status	300 istek / dakika	GET /services/{id}/status (yüksek frekanslı polling)
services_changes	120 istek / dakika	Değişiklik uç noktaları (power, rebuild, parola, upgrade)

Büyük bayiler için kova bazlı artışlar Rabisu tarafından tanımlanır. Anahtarınızın etkin limitlerini GET /auth/me yanıtındaki rate_limits alanından okuyabilirsiniz:

"rate_limits": {
  "default": 60,
  "services_read": 150,
  "services_status": 300,
  "services_changes": 120
}

Yanıt Başlıkları

Her yanıtta güncel kota bilgisi döner:

Başlık	Anlamı
X-RateLimit-Limit	Dakikadaki toplam kota
X-RateLimit-Remaining	Kalan istek sayısı
X-RateLimit-Reset	Kotanın yenileneceği Unix zaman damgası

Kota Aşımı (429)

Kota aşıldığında 429 Too Many Requests döner ve Retry-After başlığı kaç saniye beklemeniz gerektiğini bildirir:

HTTP/1.1 429 Too Many Requests
Retry-After: 42
X-RateLimit-Limit: 60
X-RateLimit-Remaining: 0
X-RateLimit-Reset: 1785000000

{
  "success": false,
  "error": {
    "code": "rate_limited",
    "message": "İstek limiti aşıldı. Lütfen daha sonra tekrar deneyin."
  },
  "meta": { "trace_id": "...", "timestamp": "..." }
}

Öneriler

• 429 alırsanız Retry-After süresi kadar bekleyip üstel geri çekilme (exponential backoff) ile tekrar deneyin.
• Servis durumu için sürekli polling yerine mümkünse Webhooks kullanın — bildirimler anlık gelir, kota tüketmez.
• Toplu işlemlerde istekleri zamana yayın; aynı anda yüzlerce istek göndermeyin.