API Hız Limitleri

Platform kararlılığını korumak ve adil kullanımı sağlamak için Hipcall, tüm /api/v3/* uç noktalarında hız limitleri uygular. Bu sayfa limitleri, bunların nasıl tespit edileceğini ve nasıl düzgün şekilde yönetileceğini açıklar.

Hangi uç noktalar hız limitlidir

/api/v3/* altındaki tüm uç noktalar, aşağıdakilerden biri ile kimlik doğrulaması yapıldığında hız limitlerini uygular:

OAuth erişim token'ı (OAuth 2.0 akışı ile verilir)
Kişisel API token'ı

Diğer uç noktalar (genel belgeler, sağlık kontrolleri, web oturum rotaları) şu anda hız limitli değildir, ancak buna güvenmemelisiniz — limitler herhangi bir zamanda eklenebilir.

Varsayılan limitler

Ayar	Değer
Sürekli hız	60 istek / dakika
Patlama kapasitesi	60 istek
Yenilenme hızı	1 istek / saniye

Limitleyici, token bucket algoritmasını kullanır. Anında en fazla 60 isteğe kadar patlama yapabilirsiniz; bundan sonra her saniyede 1 istek kapasitesi geri kazanırsınız ve maksimum 60'a kadar çıkar.

İstekler nasıl sayılır

Sayım arayan başına yapılır, global değil:

Kimlik doğrulama	Sayım birimi
OAuth erişim token'ı	(OAuth uygulaması, kullanıcı) çifti
Kişisel API token'ı	API token'ı

Bir OAuth uygulamasının her kullanıcısının kendi kovası vardır. Aynı uygulamanın iki kullanıcısı kotayı paylaşmaz. Aynı kullanıcı adına hareket eden farklı OAuth uygulamaları da kotayı paylaşmaz.

Yanıt başlıkları

Hız limiti uygulanan her yanıt (başarılı veya 429) şunları içerir:

Başlık	Açıklama
`x-ratelimit-limit`	Kova kapasitesi (maksimum patlama)
`x-ratelimit-remaining`	Kovada kalan token sayısı
`x-ratelimit-reset`	Kovanın yenileneceği Unix zaman damgası (saniye)
`retry-after`	Yeniden denemeden önce beklenecek saniye. Yalnızca `429` yanıtlarında bulunur.

Örnek:

HTTP/1.1 200 OK
x-ratelimit-limit: 60
x-ratelimit-remaining: 42
x-ratelimit-reset: 1735056000
content-type: application/json

Kısıtlanmış yanıt (429)

Kova boş olduğunda, API 429 Too Many Requests HTTP yanıtını döner:

HTTP/1.1 429 Too Many Requests
x-ratelimit-limit: 60
x-ratelimit-remaining: 0
x-ratelimit-reset: 1735056001
retry-after: 1
content-type: application/json

{
  "errors": {
    "detail": "Rate limit exceeded. Retry after 1 seconds."
  }
}

Önerilen istemci davranışı

retry-after değerine uyun. Yeniden denemeden önce en az belirtilen saniye kadar bekleyin. Hemen yeniden denemeyin.
Tekrarlanan 429'larla karşılaşırsanız jitter'lı üstel geri çekilme (exponential backoff) kullanın, böylece toplu kurtarma (thundering-herd) önlenir.
x-ratelimit-remaining değerini önceden kontrol edin. Düşükse, kısıtlanmadan önce hızınızı yavaşlatın.
Mümkün olduğunda yanıtları önbelleğe alın ve istek hacmini azaltın.
Olay yayan kaynaklar için yoklama (polling) yerine webhook kullanın.
Patlamaları yayın. Tek bir sıkı döngü, patlama bütçesini bir saniyenin altında tüketir.

Referans: geri çekilme sözde kodu

attempt = 0
while True:
    response = call_api()
    if response.status != 429:
        return response

    retry_after = int(response.headers.get("retry-after", "1"))
    sleep(retry_after + random(0, 1))      # jitter
    attempt += 1
    if attempt > MAX_RETRIES:
        raise RateLimitedError()

OAuth uygulamaları için özel limitler

Yüksek hacimli, meşru ihtiyaçları olan OAuth uygulamaları özel limitler (kapasite ve dakika başına hız) talep edebilir. Aşağıdaki bilgilerle destek ekibiyle iletişime geçin:

OAuth uygulamasının client_id değeri
Beklenen sürekli ve tepe istek hızları
Kullanım senaryosunun kısa açıklaması

Servis bozulması

Hız limiti alt sistemimiz geçici olarak kullanılamaz hale gelirse, istekler hatalı şekilde reddedilmek yerine geçirilir ("fail open"). Böyle bir süre boyunca, hız limiti başlıkları statik yedek değerler gösterebilir; bu, sınırsız kullanıma izin verildiği anlamına gelmez.