API रेफ़रेंस

ऑथेंटिकेशन

अपने डैशबोर्ड में अकाउंट → सुरक्षा से API कुंजी लें। हर रिक्वेस्ट में इसे Authorization हेडर में Bearer टोकन के रूप में भेजना ज़रूरी है:

लाइव कुंजियां pk_live_ से शुरू होती हैं। कुंजियों का स्कोप तय किया जा सकता है और उन्हें कभी भी GET /account/api-keys और DELETE /account/api-keys/{key_pub_id} के ज़रिए रद्द किया जा सकता है।

एरर

हर एरर बॉडी JSON होती है, जिसके टॉप लेवल पर detail कुंजी होती है। इसके अंदर की वैल्यू तीन में से किसी एक रूप में आती है, इसलिए पहले HTTP स्टेटस पढ़ें और detail को स्ट्रिंग, ऑब्जेक्ट या ऐरे — इनमें से किसी एक की तरह संभालें।

// 1. A plain message — most 400 / 401 / 403 / 404 responses
{ "detail": "Order not found" }

// 2. A coded error — newer endpoints (sub-users, gateways, whitelist removal).
//    Branch on detail.error.code; the message is for humans and may change.
{
  "detail": {
    "error": {
      "code": "insufficient_unallocated_traffic",
      "message": "not enough unallocated traffic on this service"
    }
  }
}

// 3. Request validation — always HTTP 422, one entry per rejected field
{
  "detail": [
    {
      "type": "value_error",
      "loc": ["body", "gb"],
      "msg": "Value error, gb must be a whole number of GB (1, 2, 3, ...); got 1.5",
      "input": 1.5
    }
  ]
}

भरोसेमंद क्लाइंट पहले स्टेटस कोड पढ़ता है, फिर जांचता है कि detail ऐसा ऑब्जेक्ट है या नहीं जिसमें error.code हो, और उसके बाद ही उसे टेक्स्ट की तरह दिखाता है। इस रेफ़रेंस में बताए गए एरर कोड हमेशा detail.error.code में होते हैं।

रेट लिमिट

रिक्वेस्ट की लिमिट प्रति IP प्रति मिनट 600 रिक्वेस्ट है। लिमिट पार करने पर 429 स्टेटस लौटता है — थोड़ा रुकें और कुछ देर बाद दोबारा कोशिश करें।

आइडेम्पोटेंसी

ऑर्डर, अवधि बढ़ाने, टॉप-अप और सब-यूज़र में बदलाव करने वाले एंडपॉइंट के लिए Idempotency-Key हेडर ज़रूरी है — इसके बिना कुछ भी चार्ज होने या बनने से पहले ही 400 लौटता है। हर नई रिक्वेस्ट के लिए एक अलग कुंजी भेजें (UUID अच्छा विकल्प है); टाइमआउट या नेटवर्क एरर के बाद उसी कुंजी के साथ दोबारा भेजने पर काम ज़्यादा से ज़्यादा एक बार ही होता है।

दोबारा भेजी गई रिक्वेस्ट मूल नतीजा लौटाती है और उसके साथ Idempotent-Replayed: true रिस्पॉन्स हेडर आता है, ताकि आप सुरक्षित रूप से छोड़ी जा सकने वाली दोबारा कोशिश को नए बदलाव से अलग पहचान सकें — सिर्फ़ बॉडी दोनों मामलों में एक जैसी होती है।

कोड लिखते समय दो अपवाद ध्यान में रखें। सब-यूज़र allocate और reclaim रीप्ले नहीं होते: दोबारा इस्तेमाल की गई कुंजी पिछले नतीजे की जगह 409 request_in_progress लौटाती है, इसलिए हर कोशिश के लिए नई कुंजी इस्तेमाल करें और स्थिति पक्की करने के लिए सब-यूज़र को दोबारा पढ़ें। और जिस कुंजी का सब-यूज़र बाद में हटाया जा चुका है, उसे दोबारा इस्तेमाल करने पर हटाए गए रिकॉर्ड की जगह 409 idempotency_key_reused मिलता है।