# Hız sınırı ve tekrar kuralları

siparis.app API isteklerini `https://api.siparis.app/v1` adresine Bearer anahtarıyla gönderirsiniz. Okuma bütçesi API bağlantısı başına 60 saniyede 600 puandır. Anahtar döndürmek bütçeyi yenilemez. Her ucun `x-read-cost` değeri [OpenAPI](https://developer.siparis.app/openapi.json) içindedir: çoğu tek kayıt 1, liste 2, desteklenen `include` toplam +1, dışa aktarma hazırlama 60 ve dosyasını indirme 5 puan; kargo fiyatı sorma, gönderi açma ve etiket indirme 10 puandır.

`RateLimit` başlığında `r` kalan puan, `t` pencerenin uzunluğudur (kayan pencere, saniye; bütçe dolduysa en geç bu kadar bekleyin). `RateLimit-Policy` içindeki `q=600`, `w=60` puan ve saniye sınırını verir. Hatalı anahtar denemesi için ayrı IP sınırı 60 saniyede 30 denemedir; geçerli anahtarla yapılan istekler bu sayaçtan etkilenmez.

Kargo fiyat sorgusu için ayrıca işletme başına 60 saniyede 20 sorgu sınırı vardır; bütün API bağlantıları ve markalar ortak sayılır. Aşımda `429 quote_rate_limited` ve beklenecek saniyeyi veren `Retry-After` döner. Gönderi açma ve panel/AI kargo işlemleri bu sayaca girmez. Fiyat sorgusundaki bakiye en çok 60 saniyelik önbellektendir; gönderi açılışında taze okunur.

## Hangi isteği ne zaman tekrarlamalı?

| Durum | Davranış |
| --- | --- |
| 400, 401, 403, 404, 422 | Önce code ve errors alanlarına göre girdiyi/anahtarı/kapsamı düzeltin |
| 429 | Retry-After başlığındaki saniye kadar bekleyin; eşzamanlı istekleri azaltın |
| GET ağ hatası veya 5xx | Retry-After varsa en az o kadar; yoksa 1, 2, 4, 8… en çok 60 saniye artan bekleme ve rastgele gecikme; deneme sayısını sınırlayın |
| POST/PATCH ağ hatası veya 5xx | Sakladığınız aynı Idempotency-Key, yöntem, yol, gövde ve varsa If-Match ile tekrar deneyin |
| 409 idempotency_in_progress | Bekleyip aynı anahtar ve gövdeyle yeniden deneyin |
| 409 export_in_progress | İşletmedeki hazırlama bitene kadar bekleyin; yeni denemede yeni anahtar kullanın |
| Webhook oluşturma/döndürmede belirsiz sonuç | Aynı anahtarla tekrar durumunu okuyun; sır tekrar gösterilmez. Sır kaybolduysa uygun geçiş süresinde yeni anahtarla sır döndürün |

`POST /v1/orders/{id}/shipments/quote` yan etkisiz fiyat sorgusudur; tekrar anahtarı istemez, ağ hatasında okuma gibi yeniden sorulabilir. Gönderi açma/iptal 202 yanıtından sonra aynı `shp_` kaydından izlenir; belirsiz sonuçta aynı anahtar ve gövde korunur. [Kargoya vermek](https://developer.siparis.app/kargo-gondermek).

Tekrar anahtarı bütün API yazmalarında (`POST`, `PATCH`) zorunludur; sipariş, webhook ve dışa aktarma buna dahildir. En çok 200 karakterdir; yeni işte benzersiz değer, aynı işin tekrarında aynı değer kullanılır. Ad alanı API bağlantısıdır; anahtar döndürmek bunu değiştirmez. Aynı tekrar anahtarını farklı yöntem, yol, gövde veya `If-Match` ile kullanmak `422 idempotency_key_reused` üretir.

Aynı Idempotency-Key ile tekrarlanan istek, ilk isteğin sonucunu (hata dahil) döndürür; yeni deneme için yeni anahtar kullanın. Kaydedilen 4xx iş hatası, koşullar sonradan düzelmiş olsa da aynı anahtarla tekrar verilir; yalnız hata kodu ve sabit açıklaması saklanır. İstek işleme alınmadan verilen kimlik, kapsam, giriş doğrulaması, hız sınırı ve `idempotency_in_progress` hataları makbuz oluşturmaz.

Tekrarda `Idempotent-Replayed: true` eklenir. Başarılı işlemin HTTP durumu ve `Location` başlığı korunur; yanıt gövdesi güncel kayıttan, bağlantının güncel kapsam ve maskelemesiyle üretilir. Siparişin `ETag` değeri güncel içerik özetidir. Kaynağa artık erişilemiyorsa 403/404 dönebilir. Yanıt gövdesi makbuzda tutulmaz; anonimleşmiş müşteri bilgisi geri gelmez. Webhook sırrı yalnız ilk oluşturma/döndürme yanıtında gösterilir, tekrar kaydında saklanmaz. Makbuzlar en az 30 gün korunur; 90 gün sonrası teknik temizlik ayrı işte yürütülür.

Olay okuyucusunda `has_more=false` sonrasında bekleme ekleyin; boş sayfa ile `has_more=true` ise ilerleyin. Çok işçide bütçeyi ortak yönetin, süresiz tekrar döngüsü kurmayın. Tekrarın ERP’de çift kayıt oluşturmaması için dış kaynak ve olay kimliklerini kalıcı tekilleştirin. Webhook alıcısının teslim tekrarları [Webhook rehberinde](https://developer.siparis.app/webhook) açıklanır.