وثائق المطوّرين
استكشاف مشكلات اتصال API و CLI و MCP وإصلاحها
عالج إخفاقات الدخول والأذونات والمخططات والرفع والكتابة غير المؤكدة دون كشف بيانات اعتماد أو تكرار عمل مقبول.
اقرأ بصيغة Markdownراجعه فريق SosoAPI ·
متصفح غير صحيح أو تسجيل دخول محلي محظور
أوقف الدخول المعلّق ثم شغّل auth login --no-open. افتح URL الجديد المطبوع في ملف المتصفح المقصود. افحص الحساب والمساحة قبل التفويض واستخدم ملفاً واحداً للرابط. إذا انشغل المنفذ 8789، حدّد المستمع ولا توقفه إلا إن كان عملية دخول بدأتها أنت.
npx sosoapi auth login --no-openlsof -nP -iTCP:8789 -sTCP:LISTEN401 و 403 والحسابات غير المتاحة
لـ 401، تحقّق من الدخول باعتماد سارٍ. لـ 403، افحص دور المساحة والنطاق والإمكانية المطلوبة. استخدم auth status وتحقّق من بريد الحساب ونوع الاعتماد المقبول. غيّر الوصول فقط إن لزم للعملية؛ تغيير ملف الأدوات لا يمنح إذناً.
افحص الحساب الاجتماعي منفصلاً. اقرأ اتصاله وإمكاناته، وأعِد الربط فقط إذا احتاج المزوّد موافقة متجددة. خطأ خدمة داخلي لا يستدعي إعادة إنشاء اتصال سليم.
400: التحقق من الصحة واختلاف الإصدارات
اقرأ الجسم ومسارات حقول التحقق. قد تحوي أخطاء التحقق ZodError؛ وقد تستخدم أخطاء المعالج error و message و code. قارن الطلب بالعقد المثبّت وحدّث حزمة العميل عند الحاجة. أصلح الحقول المذكورة دون حذف المطلوب أوإضافة مرشحات غير مدعومة.
npx sosoapi api contract --route /studio-api/scheduled-posts/409 أو 429 أو 5xx أو عملية كتابة انتهت مهلتها
لـ 409، اقرأ أحدث إصدار للمورد وإجراءاته قبل تغييره. لـ 429، انتظر حسب Retry-After وخفّض التزامن. إذا انتهت مهلة كتابة أوأعادت 5xx، احتفظ بالمعرّف وافحص النتيجة الموجودة أولاً: ربما قُبلت قبل انقطاع الاتصال.
أعِد المحاولة فقط إذا سمحت العملية وحالتها الحالية. احتفظ بالمفتاح للحمولة نفسها ولا تنشئ بديلاً لتجاوز نتيجة غير مؤكدة. أصلح المصادقة أولاً. قد تتضمن حالة مهمة معلّقة خطأ تنفيذ يستحق الفحص.
مشكلات الرفع أو اكتشاف الأدوات
يقبل الرفع المحلي وسائط مدعومة حتى 500 MiB من مجلد العمل أوالمؤقت أو Pictures/Movies/Videos أومجلدات SOSOAPI_UPLOAD_ROOTS. تُرفض المجلدات النقطية والروابط الرمزية الخارجة عن الجذور. أضف مجلد الوسائط المحدد لا مجلد المستخدم كله. لا يقرأ اتصال HTTP ملفات محلية.
إذا غابت أدوات، أعِد ربط العميل وقارن ملفه ونوع اتصاله بالمرجع. تحقّق من تحميل الأدوات في المحادثة الحالية؛ اسم خادم محفوظ وحده لا يؤكد ذلك.
مشاركة معلومات تشخيصية مفيدة بأمان
شارك اسم العملية والوقت وحالة HTTP ورمز خطأ آمناً و request_id أو x-request-id إن توفر. أضف إصدار CLI وهل MCP محلي أوبعيد. أزل الرموز والكوكيز وروابط التفويض والوسائط الموقّعة ومحتوى العملاء والمعرّفات الخاصة. شارك الخطأ المعني لا ملف اعتماد أواستجابة كاملة.