Ağlar en kötü yerde bozulur: sunucu işlemi yaptıktan sonra, ama siz yanıtı almadan önce. Idempotency anahtarı yeniden denemeyi güvenli hale getirir.
Nasıl çalışır
İstemci amaçlanan tek bir işlem için benzersiz bir anahtar oluşturur ve isteğe ekler. Sunucu anahtarı sonuçla birlikte saklar. Aynı anahtar yeniden gelirse sunucu işlemi tekrar yapmak yerine saklanan sonucu yeniden döndürür.
IETF HTTPAPI çalışma grubu bunu Idempotency-Key istek başlığı olarak standartlaştırıyor (taslak 08, Ekim 2026; henüz RFC değil). Taslak anahtarı “a unique value generated by the client which the resource uses to recognize subsequent retries of the same request” (çeviri: kaynağın aynı isteğin sonraki yeniden denemelerini tanımak için kullandığı, istemci tarafından üretilen benzersiz bir değer) olarak tanımlar ve UUID veya benzeri rastgele bir kimlik önerir. Taslaktaki hata durumları:
| Durum | Durum kodu |
|---|---|
| Gerekli olduğu yerde anahtar eksik | 400 Bad Request |
| İlk istek hâlâ işleniyor | 409 Conflict |
| Anahtar farklı bir gövdeyle yeniden kullanılmış | 422 Unprocessable Content |
AWS’nin Builders’ Library’si aynı noktayı istemci tarafından vurgular: “APIs with side effects aren’t safe to retry unless they provide idempotency.” (çeviri: Yan etkisi olan API’ler idempotency sağlamadıkça yeniden denemek için güvenli değildir.)
Neden önemli
Üstel geri çekilme (exponential backoff) ile yeniden deneme standart bir uygulamadır ve birçok SDK otomatik olarak yeniden dener. Idempotency olmadan, zaman aşımından sonraki bir yeniden deneme iki sipariş veya iki ödeme oluşturabilir. Anahtarla, ilk deneme ne yapmış olursa olsun yeniden denemek güvenlidir. Bu da onu, başında bir insan olmadan satın alan, rezervasyon yapan veya bir şey oluşturan ajanlar ve betikler için temel bir araç yapar.
BroadNet Inference’ta
BroadNet bu kalıbı saatlik anahtar satın alımında kullanır. POST /portal/keys/hourly, JSON gövdesinde bir request_id alır ve belgeler “Idempotency is required for money safety” (çeviri: Para güvenliği için idempotency zorunludur) der:
curl -X POST https://inference.broadnet.ai/portal/keys/hourly \
-H "Authorization: Bearer <portal-credential>" \
-H "Content-Type: application/json" \
-d '{"request_id":"order-20260920-001","label":"kiosk-1"}'
Bir request_id’yi yeniden kullanmak başka bir anahtar oluşturmaz veya ücret almaz. Zaman aşımı, kopan bağlantı, 409 mint_in_progress ya da bir 5xx sonrasında aynı request_id ile yeniden deneyin. Tekrarlanan istek already_issued: true ve anahtarın takma adını döndürür; ham anahtar yalnızca ilk başarılı yanıtta bulunur. Belgeler şöyle der: “Never generate a replacement id until the original result is known.” (çeviri: İlk sonuç bilinmeden asla yerine yeni bir kimlik üretmeyin.)
BroadNet, /v1/chat/completions veya transkripsiyonlar için bir idempotency anahtarı belgelemez. Orada neyin yeniden deneneceği için hata kodları ve yeniden denemeler rehberine, körü körüne yeniden denemelerin bir 429’u neden kötüleştirebileceği için hız sınırlarına bakın.