Idempotency

सभी endpoints AstroWay API स्वाभाविक रूप से इडेम्पोटेंट हैं: समान input हमेशा समान output देता है, कोई साइड इफ़ेक्ट नहीं (क्रेडिट्स की कटौती और usage लॉगिंग को छोड़कर)।

इसका मतलब है कि नेटवर्क त्रुटियों पर retry सुरक्षित है। लेकिन दोबारा अनुरोध क्रेडिट्स दो बार नहीं घटाए, इसके लिए Idempotency-Key header भेजना चाहिए।

कैसे उपयोग करें

POST /v1/chart HTTP/1.1
X-Api-Key: aw_live_...
Idempotency-Key: 01HXY2A7ZM0ABCDEF
Content-Type: application/json

{ "datetime": "1990-07-14T14:30:00", ... }

Idempotency-Key - अधिकतम 64 अक्षरों की 任意 स्ट्रिंग, प्रत्येक लॉजिकल ऑपरेशन के लिए यूनिक। अनुशंसित - ULID या UUID v4।

गारंटी

• 24 घंटे के भीतर इस कुंजी के साथ पहला अनुरोध करने के बाद, उसी कुंजी वाले दोबारा अनुरोध वही response लौटाते हैं, बिना पुनः गणना के और क्रेडिट्स की दोबारा कटौती नहीं।
• यदि अनुरोध का body मूल से अलग है: 409 Conflict लौटता है कोड idempotency_key_reuse के साथ।
• 24 घंटे बाद कुंजी भूल जाती है, उसी कुंजी के साथ नया अनुरोध सामान्य रहेगा।

टिप्पणी

Idempotency - नेटवर्क त्रुटियों पर डबल कटौती से बचाव है, कैश नहीं। कैशिंग के लिए स्वाभाविक X-Cache मैकेनिज़्म इस्तेमाल करो (5 मिनट, देखो क्रेडिट्स और लिमिट्स).

जब यह आवश्यक है

• webhook-handler में, जहाँ retry बाहरी सिस्टम से आता है (जैसे payment प्रोवाइडर या CRM इवेंट भेजता है, जिसे तू पार्स करके गणना करता है)।
• बैकग्राउंड job में, जहाँ retry: फेल्योर पर डिफ़ॉल्ट व्यवहार है।
• CI/CD pipeline में, जहाँ टेस्ट दोबारा चल सकता है।

साधारण इंटरैक्शन जैसे “यूज़र ने बटन दबाया → मैप दिखाया” में इडेम्पोटेंट की ज़रूरत नहीं है - यूज़र को परिणाम तो मिल ही जाएगा, आमतौर पर दोबारा क्लिक नहीं होते।

जब नहीं उपयोग करना चाहिए

• क्रेडिट बचाने के लिए समान अनुरोधों पर कुंजी मत लगाओ: इसके लिए X-Cache है (फ्री, 5 मिनट)।
• hash(body) से कुंजी जनरेट मत करो: तब तू Idempotency-Key का डिफ़ॉल्ट व्यवहार खो देगा (body में अंतर पर दोबारा 409)।