ত্রুটি

যখন একটি অনুরোধ ব্যর্থ হয়, 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"]
}