त्रुटियाँ और सीमाएँ

प्रबंधन त्रुटियों में error (मानव-पठनीय) और code (स्थिर) होते हैं। code और HTTP स्टेटस के आधार पर निर्णय लें, संदेश टेक्स्ट के आधार पर नहीं। Scope त्रुटियों में required और missing_scope हो सकते हैं; पुनः प्रयास योग्य प्रतिक्रियाओं में retryAfter, retryable और Retry-After हो सकते हैं। स्वामित्व विफलताएँ 404 लौटाती हैं ताकि किसी अन्य वॉलेट के संसाधन प्रकट न हों।

{ "error": "Insufficient scope", "code": "insufficient_scope", "required": "write" }

• 400: अमान्य JSON, अमान्य अनुरोध या अस्वीकृत गंतव्य।
• 401: अनुपस्थित/अमान्य प्रमाणीकरण या अस्वीकृत सिग्नेचर।
• 402: अपर्याप्त क्रेडिट या आवश्यक Slot क्षमता।
• 403: अपर्याप्त Scope या कोई अन्य स्पष्ट अनुमति प्रतिबंध।
• 404: अनुपस्थित या अन्य वॉलेट का संसाधन।
• 409: संघर्ष, सक्रिय idempotency lease, पुनः उपयोग की गई key या रोका गया एसेट।
• 410: समाप्त टॉपअप ड्राफ्ट।
• 422: भुगतान सत्यापन विफल।
• 429: रेट लिमिट या समाप्त सुरक्षा fallback क्षमता।
• 503: अनुपलब्ध कीमत, signer या अस्थायी डिपेंडेंसी।

Retry-After का सम्मान करें और jitter तथा सीमित प्रयास बजट के साथ exponential backoff का उपयोग करें। Idempotent ऑपरेशन को उसी key और body के साथ दोहराएँ। प्रमाणीकरण विफलताओं या अस्वीकृत अनुमतियों को आँख बंद करके दोबारा न आज़माएँ। केवल इसलिए दूसरा सब्सक्रिप्शन कभी न खरीदें कि पहली प्रतिक्रिया टाइमआउट हो गई। quote या ड्राफ्ट केवल तभी नया लें जब मौजूदा निर्देश अब उपयोग योग्य न हो।

Challenge और टोकन विनिमय प्रति IP प्रति मिनट 30 अनुरोधों तक सीमित हैं। टॉपअप ड्राफ्ट, सब्सक्रिप्शन खरीद और Watch निर्माण प्रति वॉलेट प्रति मिनट 10 तक सीमित हैं। Watch PATCH/DELETE प्रति मिनट 60 की अनुमति देता है; settings PUT और संदेश पूर्वावलोकन प्रति मिनट 30; अलर्ट export प्रति घंटे 10। सीमाएँ idempotency से पहले लागू होती हैं, replays सहित। Redis अनुपलब्ध होने पर एक सीमित process-local fallback उपयोग होता है; fallback क्षमता समाप्त होने पर सुरक्षा सीमाएँ fail-closed होती हैं।

प्राप्तकर्ता निर्माण और target परिवर्तन प्रति वॉलेट प्रति घंटे 10 साझा करते हैं। पुष्टि मेल के वॉलेट और canonical-destination बजट हैं। थ्रॉटल किया गया पुनः प्रेषण 429 के बजाय sent: false के साथ HTTP 200 लौटा सकता है; उस फ़ील्ड की जाँच करें। प्राप्तकर्ता निर्माण confirmationSent: false रिपोर्ट कर सकता है। लंबित target असत्यापित रहता है और परीक्षण या अलर्ट प्राप्त नहीं कर सकता।

खाता ledger और Watch सूची limit और एक अपारदर्शी (opaque) cursor स्वीकार करती हैं। nextCursor का अनुसरण null तक करें; Cursor की व्याख्या या संशोधन न करें। अलर्ट इतिहास इसके बजाय फ़िल्टर और सॉर्टिंग के साथ शून्य-आधारित page और pageSize उपयोग करता है। Export 5,000 पंक्तियों तक सीमित है। दोनों पेजिनेशन मॉडल को न मिलाएँ।

curl 'https://ftso.app/api/x402/watches?limit=20' \
  -H 'authorization: Bearer fbx_READ_TOKEN'
# Follow the returned nextCursor, URL-encoded, on the next request.

स्थिर कोड की पूरी enum OpenAPI दस्तावेज़ में प्रकाशित है। अनुमतियों के लिए ऑपरेशन संदर्भ देखें।