# שגיאות

> לכל שגיאה ב-REST API של Nodaro יש סטטוס HTTP וקוד קבוע במעטפת אחת. מה כל קוד אומר, אחרי אילו שגיאות לנסות שוב ואיך משימה שנכשלה מסבירה למה.

Source: https://nodaro.ai/he/docs/developers/api/errors

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

## מעטפת השגיאה
```json
{ "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](https://nodaro.ai/docs/developers/oauth).

## אחרי אילו שגיאות לנסות שוב
| סטטוס | מה לעשות |
| --- | --- |
| `5xx` | בדרך כלל זמנית. נסו שוב, והאריכו את ההמתנה אקספוננציאלית לפני כל ניסיון. |
| `429` | המתינו ונסו שוב, והאריכו את ההמתנה לפני כל ניסיון: למשל 5 שניות, אחר כך 10 ואחר כך 20. כשיש כותרת `Retry-After`, פעלו לפיה. |
| `402` | הוסיפו קרדיטים, או בקשו תקציב ממנהל סביבת העבודה, ואז נסו שוב. |
| `4xx` אחר | תקנו קודם את הבקשה. אותה בקשה תיכשל שוב. |

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

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

## קודי שגיאה
### 400 Bad Request
| קוד | משמעות |
| --- | --- |
| `validation_error` | גוף בקשה פגום, UUID שגוי, שדה לא תקין או cursor פגום. עם `reason: "llm_model_unpriced"`: מודל LLM שעדיין אין לו מחיר. ראו את הסעיף [מודל שעדיין אין לו מחיר](#llm-model-unpriced). |
| `limit_reached` | כבר יש לכם 10 אסימוני API, פעילים או לא. מחקו אחד קודם. |
| `invalid_workflow` | ערך ב-`workflowIds` של אסימון הוא לא תהליך במרחב האישי שלכם. |
| `token_workspace_mismatch` | אסימון שמשויך לסביבת עבודה אחת נשלח עם כותרת `X-Nodaro-Workspace` שמציינת סביבה אחרת. |
| `locked_field` | הרצה ניסתה לשנות לאן רכיב שפונה לשירות חיצוני שולח נתונים, או מאיפה הוא מביא אותם. ראו בדף ה-API [מה הרצה לא יכולה לשנות](https://nodaro.ai/docs/developers/api/workflows#what-a-run-cannot-change). |
| `image_required` | `POST /v1/generate-video` בלי פריים פתיחה, במודל שלא יכול ליצור וידאו מטקסט. ההודעה מציינת אם ייחוסים יעבדו במקום זאת. |
| `sequence_execution_required` | ההרצה כוללת רכיבים של הפקת Studio, שצריך ליצור דרך ה-API של הפקות Studio. |
| `not_workspace_scoped` | שיניתם את `visibility` בתהליך שלא נמצא בסביבת עבודה. |
| `advanced_mode_unsupported` | `advancedMode: true` במודל שאי אפשר להריץ ישירות אצל הספק שלו. |
| `advanced_mode_unavailable` | `advancedMode: true` כשהספק של המודל עצמו לא יכול לקבל בקשות. לא נגבים קרדיטים. כבו את המצב המתקדם כדי להריץ את המודל. אותו קוד יכול להגיע גם כ-`502` באמצע קריאה. במקרה כזה הקרדיטים מוחזרים, אלא אם הספק חייב על הניסיון. |
| `quote_unsupported` | `POST /v1/quote` לסוג רכיב שהפלטפורמה לא יכולה לתת לו אומדן מחיר. ההודעה מפרטת את הסוגים שאפשר לקבל להם אומדן. ראו בדף ה-API [אומדני מחיר להרצה](https://nodaro.ai/docs/developers/api/nodes#run-quotes). |
| `continuation_subset_required` | `continueFromExecutionId` בלי `nodeIds` או `continueMode`. ראו בדף ה-API [המשך הרצה](https://nodaro.ai/docs/developers/api/workflows#continue-a-run). |
| `continuation_workflow_mismatch` | ההרצה שמצוינת ב-`continueFromExecutionId` הריצה תהליך אחר. |
| `continuation_version_mismatch` | ההרצה שמצוינת ב-`continueFromExecutionId` הריצה גרסת אפליקציה שפורסמה של התהליך. |
| `render_final_node_not_found` | `renderFinal.renderNodeId` לא מציין אף רכיב של התהליך. |
| `render_final_not_a_render` | `renderFinal.renderNodeId` מציין רכיב שהוא לא רינדור של רכיב החלת רשימת עריכה. |

### 401 Unauthorized
| קוד | משמעות |
| --- | --- |
| `unauthorized` | האסימון חסר, לא תקין, פג תוקפו או בוטל. |

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

| קוד | שדות נוספים | משמעות |
| --- | --- | --- |
| `insufficient_credits` | `required`, `balance` | לחשבון נגמרו הקרדיטים. בפריסה עם חשבון חיוב אחד, פירוש השגיאה הוא שמאגר הקרדיטים של הפריסה ריק: השגיאה כוללת אז את `required`, אבל אף פעם לא את `balance`, ורק חשבון החיוב יכול להוסיף קרדיטים. |
| `insufficient_app_credits` | | הרצה של אפליקציה שפורסמה: לחשבון נגמרו הקרדיטים. |
| `budget_exceeded` | | עבודה שסביבת עבודה משלמת עליה: התקציב של סביבת העבודה לא מכסה את ההרצה. בקשו תוספת ממנהל סביבת העבודה. |
| `member_cap_exceeded` | | עבודה שסביבת עבודה משלמת עליה: הגעתם לתקרת ההוצאה האישית שלכם בסביבת העבודה הזו. |
| `user_allowance_exceeded` | `required`, `remaining` | פריסה עם חשבון חיוב אחד שאוכפת מכסה לכל משתמש: המכסה שלכם לא מספיקה להרצה. רק חשבון החיוב יכול להגדיל אותה. |
| `instance_cap_reached` | | אסימון OAuth של התקנה מחוברת באירוח עצמי: ההתקנה הוציאה את כל התקרה החודשית שלה בחשבון שחיבר אותה. הגדילו את התקרה או הסירו אותה תחת **מופעים מחוברים**. |

### 403 Forbidden
| קוד | שדות נוספים | משמעות |
| --- | --- | --- |
| `forbidden` | | האסימון מוגבל לתהליכים מסוימים והבקשה מחוצה להם, או שהנתיב דורש סשן מחובר. ראו בדף ה-API [הגבלת אסימון לתהליכים מסוימים](https://nodaro.ai/docs/developers/api/authentication#limit-a-token-to-some-workflows) ו[נתיבים שדורשים סשן מחובר](https://nodaro.ai/docs/developers/api/authentication#routes-that-need-a-signed-in-session). |
| `access_blocked` | | ב-Nodaro Cloud ובמהדורת Business, מנהל מערכת חסם את החשבון. כל פרטי הגישה של החשבון נדחים: הסשן, אסימוני ה-API ואסימוני ה-OAuth. התזמונים והטריגרים שלו נעצרים, והאפליקציות שהוא פרסם מחזירות `404 not_found`. אם אתם חושבים שזו טעות, פנו לתמיכה. |
| `insufficient_scope` | `missingScope` | לאסימון OAuth אין הרשאה שהנתיב דורש. שלחו את המשתמש שוב דרך מסך ההסכמה, עם ההרשאה הרחבה יותר. |
| `in_app_only` | | הנתיב קיים רק בשביל אפליקציית הווב של Nodaro, כמו ה-Copilot. |
| `node_not_available` | | הפריסה הזו לא מציעה לחשבון שלכם את הרכיב, או את האפשרות שבחרתם בו. ההודעה מציינת מה לא זמין. לא נגבים קרדיטים. |
| `model_not_available` | | ה-`provider` ששלחתם מציין מודל שהפריסה הזו לא מציעה. בחרו מודל אחר. לא נגבים קרדיטים. |
| `model_disabled` | | ב-Nodaro Cloud בלבד. מנהל כיבה את המודל הזה. לא משוריינים ולא נגבים קרדיטים. קניית קרדיטים לא תעזור: בחרו מודל אחר, או נסו שוב כשהמודל יופעל מחדש. |
| `edition_required` | `required_edition` | הנתיב דורש מהדורה גבוהה יותר: להסתעפות של פייפליין `cloud`, ולניהול אסימוני API `business`. |
| `not_a_member` | | הכותרת `X-Nodaro-Workspace` מציינת סביבת עבודה שאתם לא חברים פעילים בה. |
| `member_suspended` | | החברות שלכם בסביבת העבודה מושעית. |
| `personal_space_disabled` | | הארגון שלכם מאפשר לכם ליצור עבודה רק בתוך סביבת עבודה. שלחו את כותרת סביבת העבודה. |
| `project_create_not_allowed` | | רק המנהלים של סביבת העבודה יכולים ליצור פרויקטים. |
| `workspace_archived` | | כתיבה לסביבת עבודה שבארכיון, כגון שיתוף תהליך. יצירת עבודה שם נדחית במקום זאת עם `409`. |
| `not_permitted` | | אין לכם הרשאה להעביר את התהליך, או להעביר אותו לשם. |
| `sso_required` | | הפריסה מגבילה את ההתחברות לספק הזהות שלה, והחשבון של הסשן הזה לא נוצר דרכו. אסימונים לא מושפעים. |
| `subscription_required` | | חשבון בתשלום לפי שימוש הוציא קרדיטים בעורך בדפדפן. קרדיטי תשלום לפי שימוש עובדים ב-API, ב-SDK, ב-CLI וב-MCP, ולכן קריאות עם אסימון אף פעם לא מקבלות את הקוד הזה. |
| `api_tokens_payer_only` | | בפריסה עם חשבון חיוב אחד, רק החשבון הזה יכול ליצור אסימוני API. |
| `payer_balance_jwt_only` | | בפריסה כזו, חשבון החיוב קרא את היתרה של המאגר עם אסימון. רק הסשן שלו בדפדפן רשאי לעשות זאת. |
| `payer_required` | | משהו שהוא לא הסשן של חשבון החיוב בדפדפן קרא לנתיב חיוב של הפריסה. |
| `rights_confirmation_required`, `rights_authorization_required` ושאר הקודים `rights_confirmation_*` | | לייבוא של קישור אין אישור מתאים של זכויות תוכן. לא הורדו קבצים. ראו בדף ה-API [זכויות תוכן](https://nodaro.ai/docs/developers/api/content-rights#errors). |
| `import_source_disabled` | | הפריסה לא מאפשרת ייבוא מהאתר של הקישור. |
| `imports_blocked` | | ייבוא קישורים חסום בחשבון, או שהחשבון סגור, לפי מדיניות המפרים החוזרים של הפריסה. ההודעה מציינת עד מתי. ראו בדף ה-API [מפרים חוזרים](https://nodaro.ai/docs/developers/api/content-rights#repeat-infringers). |

### 404 Not Found
| קוד | משמעות |
| --- | --- |
| `not_found` | המשאב לא קיים, או שאין לכם גישה אליו. שני המקרים מקבלים בכוונה אותה תשובה, כדי שמזהה אף פעם לא יגלה אם משהו קיים. |
| `workspace_not_found` | עבודה שסביבת עבודה משלמת עליה מציינת סביבת עבודה שלא קיימת. |
| `continuation_not_found` | ההרצה שמצוינת ב-`continueFromExecutionId` לא קיימת או לא שייכת לכם. |

### 409 Conflict
| קוד | שדות נוספים | משמעות |
| --- | --- | --- |
| `already_running` | `executionId` | לתהליך כבר יש הרצה פעילה, או ש[ניסיון חוזר](https://nodaro.ai/docs/developers/embed/miniapps#retry-a-failed-run) של הרצת האפליקציה ממתין. במקום זאת, בדקו את הסטטוס של ההרצה הזו מדי כמה שניות. |
| `continuation_not_completed` | | ההרצה שמצוינת ב-`continueFromExecutionId` עדיין רצה, נכשלה או בוטלה. בלי `continueMode` אפשר להמשיך רק הרצה שהושלמה. |
| `continuation_not_failed` | | עם `"continueMode": "from-failed"`: ההרצה לא נכשלה. |
| `continuation_superseded` | `executionId`, `supersededBy` | עם `"continueMode": "from-failed"`: הרצת המשך חדשה יותר של ההרצה נכשלה, ולכן המשיכו אותה, או שהרצת ההמשך הזו כבר השלימה את כל מה שנשאר. ראו בדף ה-API [המשך הרצה שנכשלה](https://nodaro.ai/docs/developers/api/workflows#continue-a-failed-run). |
| `continuation_preview_pending` | `executionId`, `renderNodeIds`, `reviewNodeIds`, `next` | עם `"continueMode": "from-failed"`: הרצת ההמשך החדשה ביותר נעצרה לבדיקה ברכיב תצוגה מקדימה. קודם שלחו את `next` כגוף הבקשה של הרצה. |
| `continuation_subset_required` | | עם `"continueMode": "from-failed"`: לא נשאר מה להמשיך. בניסיון חוזר של הרצת אפליקציה: כל השלבים הושלמו. |
| `app_run_version_changed` | `appVersion`, `runVersion` | [ניסיון חוזר](https://nodaro.ai/docs/developers/embed/miniapps#retry-a-failed-run) של הרצת אפליקציה שנעשתה בגרסה אחרת של האפליקציה. התחילו את ההרצה מההתחלה. |
| `app_run_version_unavailable` | | ניסיון חוזר של הרצת אפליקציה שהגרסה שלה כבר לא זמינה. התחילו את ההרצה מההתחלה. |
| `workflow_conflict` | `currentVersion`, `currentUpdatedAt`, `currentRecord` | התהליך השתנה מאז הגרסה ששלחתם. מזגו את השינויים שלכם לתוך `currentRecord` ושמרו שוב. |
| `job_cancelled` | | בקשת LLM סינכרונית שמחויבת לפי השימוש, שהמשימה שלה בוטלה אחרי שהקרדיטים שלה שוריינו, אבל לפני שהקריאה שלה נשלחה. ראו את הסעיף [בקשות LLM שמחויבות לפי השימוש](#metered-llm-requests). |
| `idempotency_key_reused` | — | הרצה של רכיב הידוק פרק או הרצת ההמשך שלה (`POST /v1/tighten-episode`, `POST /v1/tighten-episode/continue`): ה-`Idempotency-Key` כבר שייך לאחת המשימות שלכם מסוג אחר, כגון יצירת תמונה. שום דבר לא נוצר ולא נגבים קרדיטים. שלחו מפתח חדש. מפתח ששייך להרצה של אותו רכיב מחזיר את ההרצה הזו, עם `202` ו-`"deduped": true`. |
| `workspace_archived` | | ניסיתם ליצור עבודה בסביבת עבודה שבארכיון או להעביר אליה עבודה. |
| `workspace_has_no_default_project` | | בקשת יצירה בסביבת עבודה לא ציינה פרויקט, ולסביבת העבודה אין פרויקט ברירת מחדל. ציינו פרויקט. |
| `move_blocked` | | העבודה נוצרה במסגרת מטלה, ואי אפשר להעביר אותה. |
| `production_capability_required` | | שמירה כללית של תהליך השפיעה על הפקת Studio, שדורשת API משלה. |
| `retained_image_in_use` | | מחיקה הייתה מסירה תמונות מוגנות, או שלהפקה עדיין יש משימות שמשתמשות בהן. קודם סיימו או בטלו את המשימות האלה. |
| `content_held` | | הקובץ נשמר כראיה לתלונה, ולכן אי אפשר למחוק אותו כרגע. ראו בדף ה-API [תוכן מוגבל](https://nodaro.ai/docs/developers/api/content-rights#restricted-content). |

### 413, 422, 429 ו-451
| סטטוס | קוד | משמעות |
| --- | --- | --- |
| 413 | | החשבון שלכם חרג ממגבלת האחסון שלו. ה-SDK זורק `StorageExceededError`. |
| 422 | `job_blocked` | מדיניות המשימות של הפריסה דחתה את היצירה לפני שהיא רצה. לא נוצרה משימה ולא נגבו קרדיטים. הציגו למשתמש שלכם את `message` כמו שהוא, ואל תנסו שוב את אותה בקשה. |
| 422 | `upload_blocked` | מדיניות ההעלאות של הפריסה דחתה קובץ לפני שהוא נשמר. הציגו את `message` כמו שהוא. |
| 422 | `offsets_not_applied` | `POST /v1/edit-plan` קיבל שדה `offsets` גולמי. קודם כתבו כל היסט במקור שלו, כ-`sources[].offsetMs`. ראו את הדף [תוכנית עריכה](https://nodaro.ai/docs/nodes/video/edit-plan#api). |
| 422 | `master_offset` | `POST /v1/edit-plan` קיבל היסט ששונה מ-0 במקור המאסטר, או במקור שממנו נוצר התמלול. לא נגבים קרדיטים. |
| 429 | `rate_limited` | מגבלת הקצב שחלה על כל אסימון API אישי. |
| 429 | `rate_limit_exceeded` | כל מגבלה אחרת: לכל כתובת, לכל נתיב, או מספר ההרצות היומי של אפליקציה שפורסמה. |
| 429 | `too_many_downloads` | כבר יש לכם 4 ייבואי וידאו שרצים. |
| 451 | `content_restricted` | ב-`GET /v1/download` או ב-`GET /v1/image-proxy` התבקש קובץ ש-Nodaro הגביל. ראו בדף ה-API [תוכן מוגבל](https://nodaro.ai/docs/developers/api/content-rights#restricted-content). |

השגיאות `job_blocked` ו-`upload_blocked` מופיעות רק בפריסות שרושמות מדיניות כזו. על קודי `429`, ראו את דף ה-API [מגבלות קצב](https://nodaro.ai/docs/developers/api/rate-limits).

### 500 ו-503
| סטטוס | קוד | משמעות |
| --- | --- | --- |
| 500 | `internal_error` | שגיאת שרת, או כשל של שירות שהשרת תלוי בו. נסו שוב, והאריכו את ההמתנה לפני כל ניסיון. |
| 502 | `advanced_mode_unavailable` | הספק של המודל עצמו דחה קריאת LLM במצב מתקדם באמצע הקריאה. הקרדיטים המשוריינים מוחזרים, אלא אם הספק חייב על הניסיון. כבו את המצב המתקדם כדי להריץ את המודל. |
| 503 | `job_start_failed` | בקשת LLM סינכרונית שמחויבת לפי השימוש לא הצליחה לרשום שהקריאה שלה מתחילה. ראו את הסעיף [בקשות LLM שמחויבות לפי השימוש](#metered-llm-requests). |
| 503 | `price_not_configured` | למודל המבוקש אין מחיר בפריסה הזו, ולכן השרת מסרב במקום לחייב בטעות. ניסיון חוזר לא יעזור. |
| 503 | `rate_limit_unavailable` | נתיב שמוציא קרדיטים לא הצליח לבדוק את מגבלת הקצב שלו. נסו שוב מאוחר יותר. |
| 503 | `provider_unavailable` | הספק של המודל לא זמין. |
| 503 | `billing_unavailable` | דיווח השימוש לא זמין במופע הזה, או שהחיוב לא זמין לרגע בניסיון חוזר של הרצת אפליקציה בסביבת עבודה. נסו שוב בעוד רגע. |

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

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

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

```json
{
"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 [למה משימה נכשלה](https://nodaro.ai/docs/developers/api/jobs#why-a-job-failed) כדי לדעת מה פירוש כל שדה ומתי לנסות מודל אחר.

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

| מחלקה | סטטוס | שדות נוספים |
| --- | --- | --- |
| `UnauthorizedError` | 401 | |
| `ForbiddenError` | 403 | `missingScope` כשהקוד הוא `insufficient_scope` |
| `ModelUnavailableError` | 403 | תת־מחלקה של `ForbiddenError` עבור `model_not_available` ו-`model_disabled`: המודל נדחה, לא מי שקרא |
| `NotFoundError` | 404 | |
| `InsufficientCreditsError` | 402 | `required`, `available`. השדה `code` הוא קוד ה-402 של הדחייה עצמה. |
| `CreditCapExceededError` | 402 | תת־מחלקה של `InsufficientCreditsError` עבור `budget_exceeded`, `member_cap_exceeded` ו-`user_allowance_exceeded`: תקרה שמישהו אחר קבע |
| `StorageExceededError` | 413 | `reason`: הערך `storage_limit_exceeded` כשהאחסון מלא, והערך `file_too_large` כשקובץ אחד חורג מהמגבלה |
| `WorkflowConflictError` | 409 | `currentVersion`, `currentUpdatedAt`, `currentRecord`. המחלקה משמשת גם להתנגשות `production_busy` של Studio. |
| `AlreadyRunningError` | 409 | `executionId`: ההרצה שכבר מתבצעת, עבור `already_running` |
| `AppRunVersionChangedError` | 409 | `runVersion`, `appVersion`, עבור `app_run_version_changed` |
| `RateLimitedError` | 429 | |
| `JobBlockedError` | 422 | |
| `StudioOpError` | 4xx | `opIndex`: איזו פעולה באצווה של Studio נדחתה |
| `NodaroError` | כל סטטוס | מחלקת הבסיס: `code`, `status`, `message` ו-`details`, השדות האחרים של המעטפת |

```ts

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 [הרצת רכיב יחיד](https://nodaro.ai/docs/developers/api/nodes#example-generate-an-image).

## שגיאות ב-CLI
| קוד יציאה | משמעות |
| --- | --- |
| `0` | הצלחה. |
| `1` | שגיאת הרשאה, משאב שלא נמצא, ארגומנט שגוי או שגיאת רשת. |
| `2` | `--watch` הסתיים וההרצה נכשלה. |
| `3` | `--watch` נעצר כי המשימה ממתינה לבדיקה. זה לא כשל: בדקו שוב מאוחר יותר. |
| `130` | `--watch` הסתיים וההרצה בוטלה. |

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

## שאלות נפוצות

### איך נראית שגיאה ב-API של Nodaro?

לכל שגיאה יש סטטוס HTTP, והגוף שלה הוא ‎{ "error": { "code": "…", "message": "…" } }‎. הקוד קבוע, ולכן פעלו לפיו. ההודעה מיועדת לבני אדם ויכולה להשתנות.

### אחרי אילו שגיאות ב-API של Nodaro כדאי לנסות שוב?

נסו שוב אחרי שגיאות 5xx ואחרי 429, והאריכו את ההמתנה אקספוננציאלית לפני כל ניסיון, למשל 5, 10 ו-20 שניות. אל תשלחו שוב בקשה שקיבלה שגיאת 4xx בלי לשנות אותה, כי אותה בקשה תיכשל שוב. בין שגיאות השרת, השגיאה 503 price_not_configured היא היוצאת מן הכלל.

### מה פירוש 402 insufficient_credits?

בחשבון אין מספיק קרדיטים כדי להתחיל את ההרצה. השגיאה כוללת את השדה required, מספר הקרדיטים שההרצה צריכה, ובדרך כלל גם את השדה balance. הוסיפו קרדיטים ב-Nodaro Cloud, ואז שלחו את הבקשה שוב.

### מהו השדה error_hint במשימה שנכשלה?

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

### מה פירוש השגיאה llm_model_unpriced?

התהליך או הבקשה מציינים מודל LLM שעדיין אין לו מחיר בשירות שבו הוא אמור לרוץ, ולכן אי אפשר להריץ אותו. התשובה היא 400 validation_error, עם השדה reason בערך llm_model_unpriced ועם השדה modelId. בחרו מודל אחר. לא נגבים קרדיטים.

### למה נתיב מחזיר 403 in_app_only?

הנתיב קיים רק בשביל הסשן של אפליקציית הווב של Nodaro, למשל ה-Copilot או פרטי הגישה השמורים לרכיב פלט Webhook. אסימוני API ואסימוני OAuth לא יכולים לקרוא לו. השתמשו במקום זאת בנקודות הקצה של התהליכים, ב-SDK או ב-MCP.