> ## Documentation Index
> Fetch the complete documentation index at: https://docs.orionpanel.com/llms.txt
> Use this file to discover all available pages before exploring further.

# ORIONPOS API Hız Limitleri, Kotalar ve Retry Stratejisi

> ORIONPOS API'nin dakika ve saniye bazlı istek kotalarını, limit aşımı durumunu ve istemci tarafı retry stratejilerini adım adım öğrenin.

ORIONPOS API, sistemin kararlı çalışmasını korumak ve tüm entegrasyonlara adil erişim sağlamak amacıyla istek hızını sınırlandırır. Uygulamanızı bu limitlere uygun şekilde tasarlamak, beklenmedik hata yanıtlarının önüne geçer.

## İstek Kotaları

<CardGroup cols={2}>
  <Card title="Dakikada Maksimum İstek" icon="clock">
    Herhangi bir dakikada API'ye gönderebileceğiniz **toplam istek sayısı** **60** ile sınırlıdır.
  </Card>

  <Card title="Saniyede Maksimum İstek" icon="bolt">
    Herhangi bir saniyede art arda gönderebileceğiniz **anlık istek sayısı** **10** ile sınırlıdır.
  </Card>
</CardGroup>

## Limit Aşımında Ne Olur?

<Warning>
  Belirlenen hız limitlerini aştığınızda API, `429 Too Many Requests` HTTP durum kodu ile yanıt verir. Bu yanıt geldiğinde mevcut isteğiniz işleme **alınmaz**; isteği kısa bir bekleme süresinin ardından yeniden göndermeniz gerekir. Limiti aşan istekleri hızla tekrar göndermek durumu daha da kötüleştirebileceğinden, aşağıda açıklanan **üstel geri çekilme (exponential backoff)** stratejisini uygulamanızı kesinlikle öneririz.
</Warning>

## İstemci Tarafında Retry Stratejisi

`429 Too Many Requests` yanıtı aldığınızda aşağıdaki **üstel geri çekilme** algoritmasını kullanın. Her başarısız denemede bekleme süresini katlayarak gereksiz yük oluşturmaktan kaçının:

<Steps>
  <Step title="İlk İsteği Gönderin">
    İsteğinizi normal şekilde gönderin. `429` yanıtı alırsanız bir sonraki adıma geçin.
  </Step>

  <Step title="Bekleme Süresini Hesaplayın">
    Bekleme süresini şu formülle hesaplayın:

    ```text theme={null}
    bekleme_süresi = min(taban * 2^deneme_sayısı + rastgele_jitter, maksimum_süre)
    ```

    | Parametre              | Önerilen Değer                  |
    | ---------------------- | ------------------------------- |
    | `taban`                | 1 saniye                        |
    | `maksimum_süre`        | 32 saniye                       |
    | `rastgele_jitter`      | 0–1 saniye arası rastgele değer |
    | Maksimum deneme sayısı | 5                               |
  </Step>

  <Step title="Bekleyin ve Tekrar Deneyin">
    Hesaplanan süre kadar bekledikten sonra isteği yeniden gönderin. 5 denemeden sonra da `429` alıyorsanız işlemi durdurun ve hatayı kayıt altına alın.
  </Step>
</Steps>

Aşağıda basit bir Python örneği verilmiştir:

```python Exponential Backoff Örneği theme={null}
import time
import random
import requests

def api_istegi_gonder(url, headers, max_deneme=5):
    taban = 1        # saniye
    maksimum = 32    # saniye

    for deneme in range(max_deneme):
        yanit = requests.get(url, headers=headers)

        if yanit.status_code == 200:
            return yanit.json()

        if yanit.status_code == 429:
            bekleme = min(taban * (2 ** deneme) + random.uniform(0, 1), maksimum)
            print(f"Hız limiti aşıldı. {bekleme:.1f} saniye bekleniyor... (Deneme {deneme + 1}/{max_deneme})")
            time.sleep(bekleme)
        else:
            # Diğer hata kodlarında yeniden deneme yapma
            yanit.raise_for_status()

    raise Exception("Maksimum deneme sayısına ulaşıldı. İstek başarısız.")
```

<Tip>
  Toplu veri aktarımı yapıyorsanız isteklerinizi sıraya koyun ve her istek arasına en az **100 ms** gecikme ekleyin. Bu basit önlem, saniye limitine çarpmadan düzenli bir istek akışı sağlar.
</Tip>

## On-Premise ORIONPOS Sunucusu Hakkında

<Note>
  ORIONPOS API, on-premise kurulu ORIONPOS sistemlerine köprü görevi görür. Bu nedenle yanıt süreleri yalnızca API katmanına değil, **hedef restoran sunucusunun durumuna** da bağlıdır. Sunucu kapalıysa, internet bağlantısı yoksa ya da bağlantı yavaşsa API'den normalden daha uzun yanıt süreleri veya zaman aşımı hataları alabilirsiniz. İstemcinizi bu senaryolara karşı dayanıklı hale getirmek için uygun **bağlantı zaman aşımı (connection timeout)** ve **okuma zaman aşımı (read timeout)** değerleri belirlemenizi öneririz.
</Note>