דילוג לתוכן

התחלה

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

שגיאה תמיד חוזרת באותו מבנה, עם סטטוס HTTP, קוד קבוע שמתאים לתוכנה והודעה באנגלית פשוטה.
409 Conflict
{
  "error": {
    "code": "project_busy",
    "message": "The project is still working on \"Reading the website\". Poll GET /projects/j57b… until status.busy is false."
  }
}

קודי שגיאה#

  • 400
    קוד
    invalid_request · invalid_json
    מה קרה
    חסר שדה, שדה מסוג לא נכון, או גוף שאינו JSON.
  • 401
    קוד
    missing_api_key · invalid_api_key
    מה קרה
    אין כותרת Authorization, או שהמפתח שגוי או בוטל.
  • 402
    קוד
    insufficient_credits
    מה קרה
    אין מספיק קרדיטים כדי להתחיל את השלב.
  • 403
    קוד
    plan_required · admin_key_required · forbidden
    מה קרה
    החבילה לא כוללת API, או שהשרת למנהלים קיבל מפתח רגיל.
  • 404
    קוד
    not_found · direction_not_found · proposal_not_found · composition_not_ready · repository_not_found
    מה קרה
    המשאב לא קיים או שייך לחשבון אחר, או שעוד לא נוצר.
  • 405
    קוד
    method_not_allowed
    מה קרה
    הנתיב קיים, בשיטת HTTP אחרת. הכותרת Allow מפרטת אילו.
  • 409
    קוד
    project_busy · research_not_ready · script_not_ready · proposal_not_pending · asset_not_ready · gift_code_used_up · gift_code_already_redeemed
    מה קרה
    הפרויקט באמצע שלב, או שעוד לא הגיע לשלב שהקריאה צריכה.
  • 410
    קוד
    gift_code_expired
    מה קרה
    תוקף קוד המתנה פג.
  • 413
    קוד
    file_too_large · repository_too_large
    מה קרה
    הקובץ גדול מ-100MB, או שהמאגר גדול מדי לייבוא.
  • 415
    קוד
    unsupported_media_type
    מה קרה
    הכתובת לא החזירה תמונה, וידאו או אודיו.
  • 422
    קוד
    download_failed · no_skills_found · archive_unreadable · import_failed
    מה קרה
    לא הצלחנו להוריד את הקובץ או לקרוא את המאגר.
  • 429
    קוד
    rate_limited
    מה קרה
    יותר מדי בקשות בדקה עם אותו מפתח.
  • 500
    קוד
    internal_error
    מה קרה
    תקלה אצלנו. אפשר לנסות שוב.
  • 502
    קוד
    github_error · stock_unavailable
    מה קרה
    שירות חיצוני לא ענה. אפשר לנסות שוב בעוד רגע.

מגבלת קצב#

60 בקשות בדקה לכל מפתח, בחלון קבוע של דקה. כל תשובה מגיעה עם הכותרות שלמטה. בקשה מעבר למגבלה מקבלת 429 עם Retry-After בשניות. ב-MCP כל POST נחשב לבקשה אחת.

X-RateLimit-Limit: 60
X-RateLimit-Remaining: 57
X-RateLimit-Reset: 1790675000   (unix seconds)
Retry-After: 12                  (429 only)

בדיקת התקדמות#

שלבים ארוכים רצים ברקע, ולכן קוראים שוב את הפרויקט עד ש-status.busy הוא false. פעם ב-3 עד 5 שניות מספיק: פרויקט אחד שנבדק כל 4 שניות צורך 15 בקשות בדקה. כשעוקבים אחרי כמה פרויקטים, כדאי לפזר את הבדיקות.

כשלב ברקע נכשל#

הפרויקט חוזר למצב לא עסוק, status.error מסביר מה קרה, ו-next הוא retry. מריצים שוב את אותו שלב: מחקר נכשל, קוראים שוב ל-research; כיוונים נכשלו, מאשרים שוב את המחקר; תסריט נכשל, בוחרים שוב את הכיוון; בנייה נכשלה, מאשרים שוב את התסריט. העבודה עצמה, עם השגיאה שלה, מופיעה ב-GET /projects/{id}/jobs.

מזהה בקשה#

לכל תשובה יש כותרת X-Request-Id. כשכותבים לתמיכה, מצרפים אותה ואנחנו מוצאים את הבקשה בלוגים.