नेटवर्क सबसे बुरी जगह पर फ़ेल होते हैं: सर्वर के काम कर लेने के बाद, लेकिन आपको जवाब मिलने से पहले। Idempotency key रीट्राई को सुरक्षित बनाती है।
यह कैसे काम करती है
क्लाइंट एक इच्छित काम के लिए एक यूनिक key बनाता है और उसे अनुरोध के साथ भेजता है। सर्वर key को नतीजे के साथ सहेज लेता है। अगर वही key फिर आए, तो सर्वर दोबारा काम करने के बजाय सहेजा हुआ नतीजा लौटा देता है।
IETF HTTPAPI वर्किंग ग्रुप इसे Idempotency-Key request हेडर के रूप में मानक बना रहा है (ड्राफ़्ट 08, अक्टूबर 2026, अभी RFC नहीं)। यह key को “a unique value generated by the client which the resource uses to recognize subsequent retries of the same request” (अनुवाद: क्लाइंट की बनाई एक यूनिक वैल्यू, जिससे रिसोर्स उसी अनुरोध के बाद के रीट्राई पहचानता है) बताता है और UUID या वैसी ही रैंडम ID की सलाह देता है। ड्राफ़्ट के एरर केस:
| स्थिति | स्टेटस |
|---|---|
| ज़रूरी होने पर भी key नहीं है | 400 Bad Request |
| पहला अनुरोध अभी चल रहा है | 409 Conflict |
| key किसी अलग body के साथ दोबारा इस्तेमाल हुई | 422 Unprocessable Content |
AWS की Builders’ Library क्लाइंट की तरफ़ से यही बात कहती है: “APIs with side effects aren’t safe to retry unless they provide idempotency.” (अनुवाद: side effect वाले API तब तक रीट्राई के लिए सुरक्षित नहीं, जब तक वे idempotency न दें।)
यह क्यों मायने रखती है
Exponential backoff के साथ रीट्राई आम चलन है, और कई SDK अपने-आप रीट्राई करते हैं। idempotency के बिना, timeout के बाद का रीट्राई दो ऑर्डर या दो चार्ज बना सकता है। key के साथ, पहली कोशिश ने चाहे जो किया हो, रीट्राई सुरक्षित है। इसलिए यह उन agents और स्क्रिप्ट के लिए एक बुनियादी औज़ार है जो बिना किसी इंसान की निगरानी के कुछ ख़रीदते, बुक करते या बनाते हैं।
BroadNet Inference पर
BroadNet यह पैटर्न hourly key ख़रीदने के लिए इस्तेमाल करता है। POST /portal/keys/hourly JSON body में एक request_id लेता है, और डॉक्स कहते हैं कि “Idempotency is required for money safety” (अनुवाद: पैसों की सुरक्षा के लिए idempotency ज़रूरी है):
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"}'
किसी request_id को दोबारा इस्तेमाल करने से न कोई और key बनती है, न कोई और चार्ज लगता है। timeout, टूटे कनेक्शन, 409 mint_in_progress या 5xx के बाद उसी request_id के साथ रीट्राई करें। दोहराया गया अनुरोध already_issued: true और key का alias लौटाता है; असली key सिर्फ़ पहले सफल जवाब में होती है। डॉक्स कहते हैं: “Never generate a replacement id until the original result is known.” (अनुवाद: जब तक मूल नतीजा पता न हो, कभी बदले में नई id न बनाएँ।)
BroadNet /v1/chat/completions या transcriptions के लिए कोई idempotency key दर्ज नहीं करता। वहाँ किसे रीट्राई करना है, इसके लिए एरर कोड और रीट्राई देखें, और यह समझने के लिए कि अंधाधुंध रीट्राई 429 को और ख़राब क्यों कर सकते हैं, रेट लिमिट देखें।