त्रुटियाँ

जब एक अनुरोध विफल होता है, तो API एक स्थिर रूप के साथ एक JSON त्रुटि एनवेलप लौटाता है। अपनी त्रुटि हैंडलिंग को मशीन-पठनीय type और code पर शाखाबद्ध करें — कभी मानव-पठनीय message पर नहीं (जो बदल सकता है)।

त्रुटि एनवेलप


{
  "error": {
    "type": "not_found_error",
    "code": "agent_not_found",
    "message": "No agent with that id exists.",
    "param": "agent_id"
  }
}

फ़ील्ड	टाइप	अर्थ
`type`	string	नीचे दी गई सात निश्चित श्रेणियों में से एक। HTTP स्टेटस से मैप होती है।
`code`	string	प्रत्येक विफलता के लिए एक स्थिर, मशीन-पठनीय पहचानकर्ता (जैसे `agent_not_found`)।
`message`	string	एक मानव-पठनीय विवरण। केवल प्रदर्शन/लॉगिंग के लिए — इस पर शाखाबद्ध न करें।
`param`	string	(वैकल्पिक) लागू होने पर, विफलता का कारण बना अनुरोध फ़ील्ड।

श्रेणियाँ

ठीक सात त्रुटि श्रेणियाँ हैं। प्रत्येक एक निश्चित HTTP स्टेटस से मैप होती है, इसलिए श्रेणी और स्टेटस कोड हमेशा सहमत होते हैं।

`type`	HTTP स्टेटस	कब होता है	उदाहरण `code`
`authentication_error`	`401`	API key अनुपस्थित, विकृत, निरस्त या अज्ञात है।	`invalid_api_key`
`permission_error`	`403`	key के पास आवश्यक scope नहीं है, या बनाने वाली रोल के पास मैप की गई RBAC अनुमति नहीं है।	`invalid_scope`, `permission_denied`
`tier_error`	`403`	आपका प्लान ऑपरेशन की अनुमति नहीं देता, या कोई सेटिंग एक प्लान सीमा का उल्लंघन करती है।	`tier_limit`
`invalid_request_error`	`400`	अनुरोध विकृत था या एक बाधा का उल्लंघन करता था।	`invalid_cursor`, `invalid_upload`, `folder_name_exists`, `folder_not_empty`, `tag_name_exists`
`not_found_error`	`404`	आपके organization में उस id वाला कोई रिसोर्स मौजूद नहीं है।	`agent_not_found`, `document_not_found`
`rate_limit_error`	`429`	आपने अपने प्लान का अनुरोध या क्वेरी भत्ता पार कर लिया।	`rate_limit_exceeded`
`api_error`	`500`	एक अप्रत्याशित upstream त्रुटि हुई — अनुरोध को पुनः प्रयास करें।	`upstream_error`

श्रेणियाँ योगात्मक हैं और कभी पुनः उपयोग नहीं की जातीं — भविष्य में एक नई श्रेणी जोड़ी जा सकती है, लेकिन एक मौजूदा श्रेणी कभी अर्थ नहीं बदलेगी, इसलिए type पर शाखाबद्ध करना सुरक्षित है।

नहीं मिला, कभी क्रॉस-organization नहीं

किसी भिन्न organization से संबंधित एक रिसोर्स id को 404 not_found_error के रूप में रिपोर्ट किया जाता है, ठीक वैसे ही जैसे यह अस्तित्व में ही न हो — API कभी 403 के साथ आपके organization के बाहर के रिसोर्स के अस्तित्व को प्रकट नहीं करता।

डुप्लिकेट-अपलोड अपवाद

एक प्रतिक्रिया जानबूझकर एक त्रुटि एनवेलप नहीं है: जब एक डॉक्यूमेंट अपलोड एक मौजूदा डॉक्यूमेंट से मेल खाता है, तो POST /knowledge/documents एक संरचित DuplicateDetected बॉडी (एक upload_session_id ले जाने वाली) के साथ 409 लौटाता है, त्रुटि एनवेलप नहीं। POST /knowledge/documents/confirm-duplicate के साथ अपलोड फिर से शुरू करें। पूरे फ़्लो के लिए Knowledge डॉक्यूमेंट पृष्ठ देखें।


{
  "upload_session_id": "ups_abc123",
  "duplicate_of": ["doc_existing456"]
}