שגיאות

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

מעטפת השגיאה

{ "error": { "code": "rate_limited", "message": "Too many requests. Max 30 per minute." } }

• השדה code הוא מזהה קבוע. פעלו לפיו.
• השדה message הוא טקסט לבני אדם. הוא יכול להשתנות, ולכן לעולם אל תבנו בדיקות על הטקסט שלו.
• חלק מהשגיאות מוסיפות שדות, שמפורטים ליד כל קוד בהמשך. רוב השדות נמצאים בתוך error; השגיאה already_running מציבה את executionId לצד error, ובדיקת מכסה שנכשלה לפני ההרצה שמה את required ואת remaining ברמה העליונה.

נקודת הקצה של אסימוני OAuth היא היוצאת מן הכלל היחידה: היא עונה בפורמט של OAuth, למשל { "error": "invalid_grant", "error_description": "…" }. ראו את הדף אפליקציות OAuth.

אחרי אילו שגיאות לנסות שוב

שלוש שגיאות שרת דורשות תשומת לב:

• ניסיון חוזר אחרי 503 price_not_configured לא יצליח: למודל אין מחיר בפריסה הזו עד שמנהל השרת יקבע לו מחיר.
• השגיאה 503 provider_unavailable בנתיב האסינכרוני של הקריאה ל-LLM עם פלט מובנה היא שגיאה קבועה בהתקנה ששולחת את הקריאות שלה למודלי שפה ל-nodaro.ai.
• בפרסום לרשתות חברתיות, 503 publish_retryable פירושו ששום דבר לא פורסם, ואפשר לשלוח את אותה בקשה שוב בבטחה, אבל 500 publish_failed פירושו שהתוצאה לא ידועה, ושליחה חוזרת עלולה לפרסם פעמיים.

קודי שגיאה

400 Bad Request

401 Unauthorized

402 Payment Required

הקודים האלה מגיעים מ-Nodaro Cloud ומפריסות שיש בהן חיוב.

403 Forbidden

404 Not Found

409 Conflict

413, 422, 429 ו-451

השגיאות job_blocked ו-upload_blocked מופיעות רק בפריסות שרושמות מדיניות כזו. על קודי 429, ראו את דף ה-API מגבלות קצב.

500 ו-503

בקשות LLM שמחויבות לפי השימוש

קריאה למודל שפה מחויבת לפי הטוקנים שהיא משתמשת בהם, ולכן הקרדיטים שלה משוריינים לפני שהקריאה מתחילה. בקשה סינכרונית מהסוג הזה, כגון רכיב יצירת טקסט, אשף הפרומפטים או POST /v1/llm/structured, יכולה להחזיר עוד שני קודים:

• 409 job_cancelled. המשימה בוטלה אחרי שהקרדיטים שלה שוריינו, אבל לפני שהקריאה שלה נשלחה. הקריאה אף פעם לא נשלחת, והקרדיטים המשוריינים מוחזרים. אל תנסו שוב את הבקשה כמו שהיא: המשימה בוטלה בכוונה.
• 503 job_start_failed. השרת לא הצליח לרשום שהקריאה מתחילה, ולכן הוא לא שלח אותה. הקרדיטים המשוריינים מוחזרים. שלחו את הבקשה שוב.

מודל שעדיין אין לו מחיר

על רכיב LLM משלמים לפי המודל, בתעריף של השירות שמריץ אותו. מודל שאין לו תעריף בשירות הזה לא יכול לרוץ. כל נתיב שהיה מתמחר אותו או מריץ אותו מחזיר 400:

{
  "error": {
    "code": "validation_error",
    "reason": "llm_model_unpriced",
    "modelId": "<model>",
    "message": "The model \"<model>\" has no price yet, so it cannot be run. Choose another model."
  }
}

• אומדנים: הנתיבים POST /v1/credits/estimate-workflow, GET /v1/credits/model-cost, POST /v1/component/estimate-credits, POST /v1/workflows/:id/render-final/estimate ונתיב ה-/estimate של כל רכיב תרחיש שימוש. הנתיב POST /v1/credits/model-costs עונה במקום זאת לכל מפתח בנפרד: הוא מציין את המפתח ב-errors, עם רשומה ב-errorCodes.
• פרסום: הנתיבים POST /v1/apps/publish ו-POST /v1/templates/publish מסרבים לפני שמשהו נכתב. בפרסום מחדש, הגרסה הנוכחית נשארת פעילה.
• הרצות: הנתיבים POST /v1/workflows/:id/run, POST /v1/app/:slug/run, POST /v1/app/:slug/runs/:runId/resume, POST /v1/component/execute, POST /v1/api/run, POST /v1/present/:token/run ונתיבי ההרצה וההמשך של כל רכיב תרחיש שימוש. הבדיקה נעשית לפני שההרצה נוצרת, כשערכי הקלט ששלחתם כבר מוחלים. אף רכיב לא רץ, ולכן לא נגבים קרדיטים. כלי ה-MCP run_app, run_workflow ו-run_component מגיעים לאותם נתיבים.
• טריגרים: קריאה ל-Webhook נדחית עם אותו 400. כשטריגר תזמון, טריגר טלגרם או טריגר של תוסף אמורים להתחיל הרצה, מדלגים עליה. כל טריגר משאיר בהיסטוריה של התהליך רשומת הרצה אחת שנכשלה, עם error_message: "llm_model_unpriced", ופעמים נוספות שהטריגר אמור להתחיל הרצה לא מוסיפות עוד רשומות.
• בתוך ההרצה: השרת בודק שוב כשהרצה מתחילה, לפני שרכיב כלשהו רץ. הבדיקה כוללת את תת־התהליכים ואת הרכיבים השמורים שההרצה מריצה. הרצה שנדחית כאן מסתיימת בסטטוס failed, עם ההודעה שלמעלה כ-error_message שלה. כשהמודל נמצא בתוך תת־תהליך, נוסף להודעה Found inside Sub-workflow node <id>. (נמצא בתוך רכיב תת־תהליך עם המזהה הזה), וכשהוא נמצא בתוך רכיב שמור, נוסף Found inside Component node <id>. (נמצא בתוך הרכיב השמור עם המזהה הזה).

שני נתיבים לקריאה בלבד עדיין מתארים את התהליך. הנתיב GET /v1/present/:token משמיט את estimatedCost ומחזיר estimatedCostUnpriced: { reason, modelId, message }. הנתיב GET /v1/api/schema משמיט את estimatedCredits ומחזיר estimatedCreditsUnpriced באותו מבנה.

כשמשימה נכשלת מאוחר יותר

גם בקשה שהצליחה יכולה ליצור משימה שנכשלת. במקרה כזה יש במשימה error_message, ובחמישה סוגי כשל גם error_hint מובנה:

• הערך { "kind": "safety-block", "class": "copyright" | "likeness" | "safety", "retried": boolean, "suggestedProvider"?: string, "subject"?: "input_video" | "input_image" | "prompt" | "audio" } כשמסנן הבטיחות של מודל חסם את הבקשה. הערך subject: "input_video" פירושו שהספק דחה את סרטון הקלט של המשימה עצמו, ולכן שלחו קליפ אחר. הערך subject: "input_image", תמיד עם class: "copyright", פירושו שהספק דחה את אחת מתמונות הקלט של המשימה, כי ייתכן שהיא מוגנת בזכויות יוצרים: שלחו תמונה אחרת, כי ניסוח מחדש של הפרומפט לא יעזור. הערך subject: "prompt" פירושו שבהודעה של הספק עצמו מצוין הפרומפט, ולכן שנו את הפרומפט. הערך subject: "audio" פירושו שההודעה של הספק עצמו מייחסת את הבעיה לאודיו שנוצר, ולא לתמונה. התייחסו ל-subject שאתם לא מכירים כאילו הוא לא קיים.
• הערך { "kind": "policy-block", "policyId": string, "reason": string, "hookPoint": "request" | "result" } כשהמדיניות של פריסה דחתה אותה.
• הערך { "kind": "credits", "code": string } כשהקרדיטים של המשימה נגמרו באמצע, למשל insufficient_credits או מגבלה של סביבת עבודה כגון budget_exceeded.
• הערך { "kind": "input-refused", "subject": "input_video" } כשהספק דחה את סרטון הקלט של המשימה בלי לציין סוג של מדיניות תוכן. לא מוצע מודל אחר. שלחו קליפ אחר.
• הערך { "kind": "request-refused", "subject"?: "input_video" } כשהספק דחה את הבקשה כפי שנשלחה, וציין בה בעיה: הגדרה, פורמט או גודל של קובץ, או אורך הפרומפט. אותה בקשה תידחה שוב, ולכן שנו את תמונות הקלט, את הסרטון, את הפרומפט או את ההגדרות. הערך subject: "input_video" מופיע כשההודעה של הספק מציינת את סרטון הקלט כבעיה, למשל את האורך או הגודל שלו, או שלא נמצאה בו דמות, ולכן שלחו קליפ אחר. זו לא חסימה של מדיניות תוכן.

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

שגיאות ב-SDK

החבילה @nodaro/sdk זורקת שגיאה עם טיפוס על כל תגובה שנכשלה. תפסו קודם את המחלקה הספציפית ביותר:

import {
  NodaroError,
  ForbiddenError,
  InsufficientCreditsError,
  RateLimitedError,
} from '@nodaro/sdk'

try {
  await client.workflows.run(workflowId)
} catch (err) {
  if (err instanceof InsufficientCreditsError) {
    showPaywall({ required: err.required, available: err.available })
  } else if (err instanceof ForbiddenError && err.missingScope) {
    requestConsent([err.missingScope])
  } else if (err instanceof RateLimitedError) {
    await new Promise((r) => setTimeout(r, 5_000))
  } else if (err instanceof NodaroError) {
    console.error(`API error ${err.status} (${err.code}): ${err.message}`)
  } else {
    throw err // a network failure, not an API error
  }
}

פונקציות העזר לתשאול מוסיפות שגיאות משלהן, כגון JobFailedError ו-JobTimeoutError. ראו בדף ה-API הרצת רכיב יחיד.

שגיאות ב-CLI

עם --json, ה-CLI מדפיס את המטען ויוצא כרגיל, במקום להשתמש בקודים 2, 3 ו-130, ולכן בדקו את .status בעצמכם.