תיעוד למפתחים
פתרון בעיות בחיבורי 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 מקומי או מרוחק. הסירו אסימונים, cookies, קישורי הרשאה, כתובות URL חתומות למדיה, תוכן לקוחות ומזהים פרטיים. שתפו את השגיאה הרלוונטית במקום קובץ אמצעי גישה או תגובה מלאה.