BroadRouter
Başlayın

Idempotency anahtarı (idempotency key)

Güncellendi

Idempotency anahtarı, istemcinin ödeme veya satın alma gibi durum değiştiren bir isteğe eklediği, genellikle UUID gibi rastgele bir kimlik olan benzersiz bir değerdir. Aynı istek aynı anahtarla yeniden gönderilirse sunucu işlemi ikinci kez yapmak yerine ilk sonucu döndürür.

Diğer adları: idempotency anahtarı, idempotent istek, güvenli yeniden deneme, tekrarsız istek, idempotency key, Idempotency-Key header, idempotency token, idempotent request, idempotent retry

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.

Sık sorulan sorular

Ne zaman yeni bir idempotency anahtarı oluşturmalıyım?

Yalnızca yeni bir işlem amaçladığınızda. Tek bir işlemin her yeniden denemesinde aynı anahtarı kullanın ve ilk denemenin sonucunu öğrenene kadar yenisini oluşturmayın.

LLM chat completion isteklerinin idempotency anahtarına ihtiyacı var mı?

Metin üretmenin kalıcı bir yan etkisi yoktur; tekrarlanan bir sohbet isteği genellikle yalnızca yeniden token maliyeti çıkarır. Anahtar, para tahsil eden veya kaynak oluşturan çağrılarda önemlidir. BroadNet bunu chat completions için değil, yalnızca saatlik anahtar satın alımları için belgeler.

Bir anahtarı farklı bir istek gövdesiyle yeniden kullanırsam ne olur?

IETF taslağına göre sunucu bunu 422 Unprocessable Content ile reddetmelidir, çünkü anahtar zaten başka bir isteğe bağlıdır.

Markdown olarak okuChatGPT asistanına sorClaude asistanına sorPerplexity asistanına sor