आइडेम्पोटेंट रिक्वेस्ट

रिक्वेस्ट तब भी असफल हो सकती है, जब Sursa काम पहले ही कर चुका हो: कनेक्शन टूट जाता है, या रिस्पॉन्स आने से पहले आपकी प्रोसेस रीस्टार्ट हो जाती है। अगर आप वही POST फिर भेजते हैं, तो दूसरा कार्ड या दूसरा वेबहुक बन सकता है। आइडेम्पोटेंसी कुंजी ऐसा होने से रोकती है।

हर POST और PATCH के साथ Idempotency-Key हेडर भेजें। अगर Sursa इस कुंजी वाली रिक्वेस्ट पहले देख चुका है, तो वह ऑपरेशन दोबारा नहीं चलाता: वह पहली बार सेव किया गया रिस्पॉन्स लौटाता है।

curl -X POST https://api.sursa.com/v1/cards/text \
  -H "Authorization: Bearer $SURSA_API_KEY" \
  -H "Idempotency-Key: 6f1d2c9e-7b0a-4c43-9a51-0d6c1c1f8e21" \
  -H "Content-Type: application/json" \
  -d '{"title": "Refund policy", "body_markdown": "Refunds are processed within 14 days."}'

दोहराई गई रिक्वेस्ट को पहली रिक्वेस्ट जैसा ही स्टेटस और बॉडी मिलती है, एक अतिरिक्त हेडर के साथ:

HTTP/1.1 200 OK
Idempotency-Replayed: true
X-Request-Id: 01JB7R…

दोहराई गई रिक्वेस्ट का अपना X-Request-Id होता है।

कुंजी चुनना

हर लॉजिकल ऑपरेशन के लिए नया रैंडम मान इस्तेमाल करें, जैसे UUID v4: “यह कार्ड बनाएँ”, “यह वेबहुक रजिस्टर करें”। उस ऑपरेशन के हर रीट्राई के लिए वही मान इस्तेमाल करें, और किसी दूसरे ऑपरेशन के लिए कभी नहीं।
अच्छी कुंजी आपके अपने डेटा से बनती है, अगर ऐसा डेटा हो, उदाहरण के लिए sync-2026-10-24-record-1042। तब रीस्टार्ट हुआ जॉब भी, जिसकी मेमोरी मिट गई हो, वही कुंजी फिर से भेजता है।
कुंजी 1 से 255 प्रिंट होने वाले ASCII अक्षरों की होती है। इसके अलावा कुछ भी हो, तो कोड api.idempotency_key_invalid के साथ 400 लौटता है।

Sursa कुंजी के साथ क्या करता है

स्थिति	रिस्पॉन्स
इस कुंजी वाली पहली रिक्वेस्ट	ऑपरेशन हमेशा की तरह चलता है।
वही कुंजी, वही रिक्वेस्ट, पहली `2xx` या `4xx` के साथ पूरी हुई	सेव किया गया रिस्पॉन्स, `Idempotency-Replayed: true` के साथ। ऑपरेशन दोबारा नहीं चलता।
वही कुंजी, पहली रिक्वेस्ट अभी चल रही है	`Retry-After: 1` के साथ `409` `api.idempotency_in_progress`। इंतज़ार करें और रीट्राई करें।
वही कुंजी, पर अलग मेथड, पाथ, `Content-Type` या बॉडी	`409` `api.idempotency_mismatch`। कुंजी पहले ही किसी दूसरी रिक्वेस्ट ने ले ली है।
पहली रिक्वेस्ट `5xx` या `429` के साथ पूरी हुई	कुंजी छोड़ दी जाती है: उसके साथ अगली रिक्वेस्ट ऑपरेशन को फिर से चलाती है।

कुंजी 24 घंटे तक मान्य रहती है। उसके बाद वही कुंजी नया ऑपरेशन शुरू करती है।
कुंजियाँ हर संगठन और हर कॉल करने वाले के लिए अलग होती हैं: दो अलग API कुंजियाँ एक-दूसरे पर असर डाले बिना एक ही मान इस्तेमाल कर सकती हैं।
4xx वाला एरर रिस्पॉन्स भी सेव होता है। जो रिक्वेस्ट वैलिडेशन में असफल रही, वह उसी कुंजी के साथ दोहराने पर उसी तरह असफल होती है; उसे ठीक करें और नई कुंजी के साथ भेजें।

किन रिक्वेस्ट को इसकी ज़रूरत है

मेथड	Idempotency-Key
`POST`, `PATCH`	भेजें। जो भी एंडपॉइंट दोहराव के लिए अपना रिस्पॉन्स सेव करता है, उस पर API रेफ़रेंस में यह हेडर दिया गया है।
`GET`, `PUT`, `DELETE`	ज़रूरत नहीं: अपने मतलब से ही इन मेथड को दोहराना सुरक्षित है। हेडर स्वीकार किया जाता है, पर उसका कोई असर नहीं होता।
सिर्फ़ पढ़ने वाला `POST`, जैसे खोज, वित्तीय रिपोर्ट और `POST /v1/catalog/resolve`	स्वीकार किया जाता है, पर कुछ सेव नहीं होता: रिक्वेस्ट बस फिर से चलती है।

कुछ ऑपरेशन हेडर के बिना भी दोहराने के लिए सुरक्षित हैं:

PUT /v1/cards-by-external-id/{external_id} आपकी ID वाला कार्ड बनाता है या उसे बदल देता है; उसी कंटेंट के साथ दोहराने पर कुछ नहीं बदलता।
कस्टम स्रोत के दस्तावेज़ आपके external_id से पहचाने जाते हैं; वही दस्तावेज़ फिर से भेजने पर unchanged लौटता है।
POST /v1/chat का स्ट्रीम किया गया जवाब हेडर के बजाय बॉडी का request_id फ़ील्ड इस्तेमाल करता है। देखें सवाल-जवाब बॉट बनाना।

सुरक्षित रीट्राई

कुंजी को एरर के रीट्राई नियमों के साथ इस्तेमाल करें: कुंजी पहले प्रयास से पहले एक बार बनाएँ, और उसी ऑपरेशन के हर प्रयास के साथ उसे भेजें।