לחבר AI ל-Notion: 3 בקשות בשנייה זה פחות ממה שנשמע

סוכן AI שמעדכן מסד נתונים שלם ב-Notion - למשל מוסיף תקציר לכל עמוד במאגר ידע - ומתחיל לקבל שגיאות 429 אחרי כמה עשרות עמודים, לא נתקל בבעיה ברמת ה-AI. הוא פשוט חורג ממגבלת הקצב של Notion API, שהיא נמוכה יותר ממה שרוב המפתחים מצפים.

הקצב: 3 בקשות בשנייה, לא יותר בממוצע

לפי Notion, לכל חיבור (integration) מותר ממוצע של 3 בקשות בשנייה, עם אפשרות לפרצים קצרים מעל זה - אבל לא שימוש מתמשך בקצב גבוה יותר. יש גם מגבלה נוספת ברמת ה-Workspace כולו, משותפת לכל האינטגרציות הפעילות בו. עבור סוכן שקורא עמוד, שולח אותו ל-AI, וכותב את התוצאה בחזרה - שלוש קריאות API לכל פריט - זה אומר בפועל פחות מפריט אחד בשנייה בממוצע, לא שלושה.

בפועל, ההקמה הטכנית שמונעת את הבעיה היא פשוטה: מעבדים את העמודים אחד-אחד ברצף (לא כולם במקביל), ומוסיפים השהיה קצרה - כשליש שנייה - בין פריט לפריט, כדי להישאר בבטחון מתחת לממוצע של 3 בקשות בשנייה. זו התאמה קלה שכל מפתח שמקים את האינטגרציה יכול להוסיף מיד בהתחלה, לפני שהיא בכלל הופכת לבעיה.

מגבלת התוכן: 100 בלוקים למערך, לא לתכונה

לפי אותו מקור, בקשה בודדת מוגבלת ל-1,000 אלמנטי בלוק בסך הכל ו-500KB, עם הגבלות ברמת שדה - טקסט עשיר מוגבל ל-2,000 תווים, ומערכי בלוקים (block arrays) ל-100 אלמנטים בבקשה אחת. חשוב להבין: אלה מגבלות על מה שמכניסים בקריאת API בודדת, לא על כמה תוכן עמוד יכול להכיל בסך הכל - עמוד יכול להיות ארוך הרבה יותר, פשוט לא ניתן לכתוב את כולו בקריאה אחת אם הוא חורג מהמגבלות האלה.

מה זה אומר לסוכן שמייצר תוכן ארוך

סוכן AI שמייצר עמוד Notion שלם - למשל דוח מפורט עם הרבה כותרות משנה, רשימות וטבלאות - עלול לייצר יותר מ-100 בלוקים בפלט אחד. אם הקוד מנסה לשלוח את כל זה בקריאת blocks.children.append בודדת, הבקשה תיכשל. הפתרון: לפצל את התוכן לקבוצות של עד 100 בלוקים ולשלוח אותן ברצף, לא בבת אחת - וכמובן להתחשב במגבלת הקצב בין הקריאות הנפרדות.

מקרה קצה: כמה אינטגרציות על אותו Workspace

אם יש כמה אוטומציות שונות שפועלות במקביל על אותו workspace ב-Notion (למשל בוט AI לתקצירים וגם אוטומציה נפרדת לסנכרון משימות), המגבלה ברמת ה-workspace משותפת ביניהן - גם אם כל אינטגרציה בפני עצמה נשארת מתחת ל-3 בקשות בשנייה, השילוב של שתיהן יחד עלול לחצות את התקרה המשותפת. שווה למפות מראש כמה אינטגרציות פעילות בו-זמנית על אותו workspace, ולא להניח שכל בוט "מקבל" את המכסה המלאה לעצמו - הבנה שלרוב מגיעה רק אחרי ששתי אוטומציות "מתחרות" זו בזו על אותה מכסה בלי ששום צד יודע על קיומו של האחר.

דוגמה מספרית: מסד נתונים של 300 עמודים

מאגר ידע ב-Notion עם 300 עמודים שכל אחד צריך לעבור עדכון (קריאה, ניתוח AI, כתיבה בחזרה) - שלוש קריאות API לעמוד, 900 קריאות בסך הכל. בקצב בטוח של 2.5 בקשות בשנייה בממוצע (מתחת ל-3 המותרות, עם שוליים לפרצים), זה לוקח כ-360 שניות - 6 דקות בערך, לא כולל זמן התגובה של קריאת ה-AI עצמה. אם מוסיפים גם 2-3 שניות לכל קריאת AI (תלוי במודל ובאורך הטקסט), הזמן הכולל יכול להגיע לעשרות דקות למאגר בגודל הזה - שווה לתכנן זאת מראש ולא להריץ עדכון מלא כזה בשעת עומס, אלא כמשימת רקע.

למה retry עיוור לא פותר את הבעיה

טעות נפוצה: להוסיף לוגיקת retry אוטומטית שמנסה שוב מיד כשמקבלים 429, בלי המתנה משמעותית. זה לא רק לא עוזר - זה מחמיר, כי כל ניסיון חוזר מיידי הוא עוד בקשה שנספרת במכסה שכבר נחצתה, ומרחיק עוד יותר את הרגע שבו הקצב חוזר להיות פנוי. retry נכון צריך backoff מעריכי (המתנה שגדלה עם כל ניסיון כושל) ולא ניסיון מיידי חוזר - אחרת הבוט "רב" עם עצמו על אותה מכסה במקום לחכות לה שתתפנה.

מה לנסות עכשיו

לפני שמריצים סוכן AI שמעדכן הרבה עמודים ב-Notion, להוסיף השהיה מחושבת בין קריאות (לא לסמוך על retry אחרי 429 בלבד), ולבדוק את גודל התוכן שהסוכן מייצר לעמוד בודד - אם הוא מייצר יותר מ-100 בלוקים, לתכנן מראש פיצול לכמה קריאות API במקום לגלות את המגבלה רק כשהבקשה כבר נכשלת. שילוב של השהיה מתוכננת מראש עם backoff מעריכי לניסיונות חוזרים הוא ההבדל בין תהליך שרץ בשקט לבין תהליך שנתקע כל כמה עשרות עמודים.