Idempotency
Idempotency-Key başlığı ve idempotency_key alanı, 24 saatlik saklama, aynı/farklı gövde davranışı, sürmekte olan istek kirası, hangi işlemlerin desteklediği ve SDK'lardaki otomatik anahtar.
Ağ hatası ya da zaman aşımı sonrası güvenle yeniden deneyebilmek için yazma işlemlerinde idempotency anahtarı kullanın: aynı anahtarla tekrarlanan istek ikinci bir kaynak oluşturmaz, ilk yanıt döner.
Kullanım
POST /v1/notifications HTTP/1.1
Authorization: Bearer hs_live_…
Idempotency-Key: order-1001
Content-Type: application/json
{ "app_id": "app_…", "target": { "include_external_ids": ["user_42"] }, "contents": { "tr": "…" } }- Başlık tercih edilen yoldur; OneSignal uyumu için gövdedeki
idempotency_keyalanı da kabul edilir. İkisi birlikte verilip farklıysa400 HS_VALIDATION_ERROR. - Anahtar en fazla 255 karakterdir ve app başına benzersiz alanda tutulur; sipariş numarası gibi iş anlamlı bir değer ya da UUID kullanın.
- Hangi işlemlerin desteklediği referansta parametre tablosunda
Idempotency-Keybaşlığıyla görünür: baştaPOST /v1/notificationsvePOST /v1/apps/{app_id}/users(upsert).
Davranış
| Durum | Yanıt |
|---|---|
| Yeni anahtar | İstek işlenir; yanıt ve gövde özeti (SHA-256) 24 saat saklanır |
| Aynı anahtar + aynı gövde (24 saat içinde) | Saklanan yanıt aynen döner (aynı id, aynı durum kodu); yeni mesaj oluşmaz |
| Aynı anahtar + farklı gövde | 409 HS_IDEMPOTENCY_CONFLICT |
| Aynı anahtar, ilk istek hâlâ işleniyor | 409 HS_IDEMPOTENCY_IN_PROGRESS — kısa süre sonra aynı istekle yeniden deneyin |
| İlk istek sırasında süreç çöktü | Kayıt 2 dakikalık kira süresi sonunda serbest kalır; yeniden deneme devralır |
| 24 saat sonra | Anahtar yeniden kullanılabilir (yeni işlem) |
Eşzamanlı aynı anahtarlı istekler veritabanı düzeyinde sıraya girer (tek kazanan); yarışta kaybeden 409 HS_IDEMPOTENCY_IN_PROGRESS alır.
SDK'larda
Sunucu SDK'ları autoIdempotencyKey (varsayılan açık) ile idempotent işlemlerde anahtar verilmemişse otomatik UUID üretir ve yeniden denemelerde aynı anahtarı kullanır; böylece 429/5xx sonrası tekrar çift mesaj üretmez. Açık anahtar: Node hs.notifications.create(body, { idempotencyKey }) ya da gövdede idempotency_key; Python/Ruby idempotency_key=; Go pushizo.WithIdempotencyKey("…"); Java RequestOptions.builder().idempotencyKey("…"); .NET new RequestOptions { IdempotencyKey = "…" }; PHP create([...,'idempotency_key' => '…']).
Diğer yazma işlemleri
Idempotency anahtarı desteklemeyen işlemler için doğal idempotency kullanın: kullanıcı/alias/abonelik yazma uçları external_id/token bazlı upsert davranışına sahiptir; kampanya durum geçişleri (send, pause, cancel) tekrarlandığında mevcut durumu döner ya da 409 HS_CONFLICT verir; webhook alıcı tarafında Pushizo-Event-Id ile tekrarları ayıklayın.
Hız sınırları ve kota
Plan bazlı API istek hızı (api_rps), X-RateLimit başlıkları, 429 ve Retry-After davranışı, uç başına özel sınırlar, nginx IP sınırları, plan kotaları ve SDK yeniden deneme kuralları.
Sayfalama, filtreleme ve sıralama
Cursor tabanlı listeleme (limit, cursor, next_cursor, has_more), cursor biçimi ve geçerliliği, filter[...] ve sort parametreleri, SDK'larda tüm sayfaları dolaşma yardımcıları.