מגבלות קצב ושגיאות

זמין בתוכניותProResearch

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

מגבלות

שתי מגבלות חלות על כל קריאה שמשתמשת במפתח:

• לכל מפתח, לשעה. לכל מפתח יש מגבלה שעתית משלו, עם תקרה של המקסימום של התוכנית שלכם.
• לכל חשבון, ליום. כל קריאות ה-REST שלכם חולקות תקציב יומי אחד. היום הוא לפי UTC ומתאפס ב-00:00 UTC.

המספרים לכל תוכנית נמצאים בטבלה במפתחות, הרשאות ומגבלות. לכמה נתיבים יש מגבלה נוספת קצרה לדקה: שאילת שאלה (POST /ask) והתחלה או סיום של העלאה מאפשרים מספר מוגבל של קריאות בדקה.

כותרות

כל תשובה לקריאה שעברה את הבדיקה השעתית נושאת:

• X-RateLimit-Limit: המגבלה התקפה למפתח הזה.
• X-RateLimit-Remaining: הקריאות שנותרו בשעה הנוכחית.

כשחרגתם ממגבלה התשובה היא 429 עם Retry-After, מספר השניות להמתנה.

HTTP/1.1 429 Too Many Requests
X-RateLimit-Limit: 600
X-RateLimit-Remaining: 0
Retry-After: 1260

ניסיון חוזר בנימוס

המתינו Retry-After שניות ונסו שוב. אל תנסו שוב מיד בלולאה. סקריפט שמבצע הרבה קריאות צריך לעצור כשהגיע למגבלה היומית ולהמשיך למחרת. הדוגמה בדוגמאות מראה פונקציית בקשה שעושה זאת.

GET /rest/v2/usage אומר לכם כמה מהיום ניצלתם.

מבנה השגיאה

כל סירוב משתמש במבנה JSON אחד. success הוא false, ו-error מכיל את הפרטים.

{
  "success": false,
  "error": {
    "statusCode": 403,
    "message": "This API key lacks the scope read:library.",
    "code": "SCOPE_REQUIRED",
    "details": { "scopes": ["read:library"] },
    "timestamp": "2026-11-04T09:00:00.000Z",
    "path": "/rest/v2/search",
    "method": "GET"
  }
}

code הוא החלק שמיועד למכונה. הוא יכול להיעדר בתשובות אימות פשוטות או "לא נמצא", שבהן statusCode ו-message נושאים את המשמעות. message יכול להיות רשימת מחרוזות כשכמה שדות שגויים.

קודי סטטוס ושגיאה

סטטוס	קוד	משמעות
400	-	הבקשה פגומה. פרמטר שאילתה או שדה בגוף שהנתיב לא מכיר הוא גם 400.
400	SCOPE_NOT_ALLOWED	ביקשתם בעת יצירת מפתח הרשאה שהתוכנית שלכם אינה כוללת.
401	API_KEY_INVALID	המפתח חסר, לא מוכר, בוטל, פג תוקפו או נחסם. התשובה נושאת WWW-Authenticate: Bearer realm="readsira".
401	API_KEY_IN_QUERY	המפתח נשלח בכתובת. שלחו אותו בכותרת.
402	PLAN_REQUIRED	לתוכנית אין REST API (Free), או אין העלאות. מפתחות MCP עדיין עובדים ב-/mcp.
402	PLAN_LIMIT_REACHED	הגעתם למגבלת ספירה, למשל תשובות בחודש.
402	AI_QUOTA_EXCEEDED	תקציב ה-AI של החודש נוצל (POST /ask).
402	PROJECT_LIMIT_REACHED	פרויקט הגיע למגבלת הפריטים של התוכנית שלכם.
403	SCOPE_REQUIRED	למפתח חסרה ההרשאה שהנתיב צריך. error.details.scopes נותן לה שם.
404	-	לא נמצא, או לא שלכם. ה-API לא אומר איזה מהשניים.
409	PROJECT_ARCHIVED	ניסיתם לכתוב לפרויקט בארכיון.
429	RATE_LIMITED	המגבלה השעתית או היומית. ב-error.details יש window (hour או day), limit ו-retryAfterSeconds.
503	AI_PAUSED	ה-AI מושהה להיום (POST /ask בלבד). החיפוש ממשיך לעבוד.

429 בלי קוד מגיע מהמגבלה הקצרה לדקה בנתיב. המתינו ונסו שוב באותה דרך.

מגבלות על הקלט

ה-API בודק כל קלט ודוחה את כל הבקשה עם 400 כשאחד מהם מחוץ לטווח.

נתיב	קלט	מותר
GET /search	q	1 עד 500 תווים
GET /search	limit	1 עד 20, ברירת מחדל 8
POST /ask	question	1 עד 2000 תווים
POST /ask	bookmarkIds	1 עד 50 מזהים
GET /documents/:id	offset	0 תווים או יותר
GET /documents/:id	maxChars	1 עד 20,000, ברירת מחדל 12,000
GET /documents/:id/chunks	limit	1 עד 100, ברירת מחדל 20
GET /documents/:id/transcript	limit	1 עד 500
GET /projects	limit	1 עד 50, ברירת מחדל 20
GET /projects/:id/context	q	1 עד 500 תווים
GET /projects/:id/context	maxChars	1 עד 32,000, ברירת מחדל 16,000

לכל נתיב יש רשימה מלאה עם סוגים במדריך העזר ל-REST API v2.

קשור

• אימות ומפתחות API
• עימוד
• מפתחות, הרשאות ומגבלות