# שגיאות

כל נקודת קצה נכשלת באותה דרך: סטטוס HTTP ומעטפת JSON אחת.

```json
{
  "error": {
    "type": "invalid_request",
    "code": "invalid_input",
    "message": "duration must be one of 5, 10.",
    "param": "duration",
    "details": [ { "param": "duration", "message": "duration must be one of 5, 10." } ],
    "request_id": null,
    "doc_url": "https://doitong.com/developers/docs/errors#invalid_input"
  }
}
```

| שדה | משמעות |
|---|---|
| `type` | הסיווג הכללי של השגיאה. לפי זה יש להחליט מה לעשות. |
| `code` | הסיבה המדויקת, יציבה וקריאה למכונה. לכל קוד יש סעיף בהמשך; `doc_url` מקשר אליו. |
| `message` | הסבר קריא לבני אדם, בטוח לרישום או להצגה למפתח. |
| `param` | פרמטר הקלט או הכותרת הבעייתיים, אם יש כאלה. |
| `details` | עבור שגיאות קלט, כל הבעיות שנמצאו: `[{ "param", "message" }]`. |
| `request_id` | הבקשה שאליה הדבר מתייחס, אם קיימת. |

לא נגבים קרדיטי API עבור קריאה שמחזירה שגיאה. בקשה שנכשלת *לאחר* שהתקבלה נשארת בסטטוס
`failed`, כוללת `error: { "type", "code", "message" }` באובייקט הבקשה, ומקבלת החזר אוטומטי.

## סוגים

| סוג | סטטוס HTTP | מה לעשות |
|---|---|---|
| `invalid_request` | 400, 413 או 422 | לתקן את הבקשה. ניסיון חוזר של אותה קריאה ייכשל שוב. |
| `authentication_error` | 401 | לשלוח מפתח תקף ב־`Authorization: Bearer <key>`. |
| `permission_error` | 403 | להשתמש במפתח עם ההרשאה הנדרשת. |
| `not_found` | 404 | לבדוק את מזהה המודל או את מזהה הבקשה. |
| `insufficient_credits` | 402 | לטעון את יתרת ה־API (`top_up_url` בשגיאה). |
| `budget_exceeded` | 402 | התקציב של המפתח עצמו נוצל. סופי: לבקש מבעל המפתח להגדיל אותו. |
| `conflict` | 409 | המשאב אינו במצב שמאפשר את הקריאה הזו. |
| `rate_limited` | 429 | להמתין `Retry-After` שניות ואז לנסות שוב. |
| `upstream_error` | 502 | עורף המודל נכשל. בטוח לנסות שוב עם אותו `Idempotency-Key`: הקריאה תתבצע שוב; לא חויבתם. |
| `service_unavailable` | 503 | ה־API מושהה או שתלות אינה זמינה. לנסות שוב מאוחר יותר. |
| `internal_error` | 500 | באג אצלנו. לנסות שוב; אם הבעיה נמשכת, לפנות לתמיכה עם השעה ו־`request_id`. |

## קודים

### `invalid_request`

בקשה פגומה כללית (400).

### `invalid_json`

גוף הבקשה אינו JSON תקין (400).

### `invalid_body`

גוף הבקשה הוא JSON תקין אך אינו אובייקט; קלט המודל חייב להיות אובייקט JSON (400).

### `body_too_large`

גוף הבקשה גדול מ־16 MB (413). יש להעלות קבצים גדולים ולהעביר במקום זאת את ה־URL שלהם (ראו [קבצים](https://doitong.com/developers/docs/files)).

### `invalid_parameter`

לפרמטר שאילתה יש ערך שגוי, למשל `limit` מחוץ לטווח 1 עד 100, `wait` שאינו מספר, `status` או `category` לא מוכרים,
או `storage` שאינו `permanent` / `temporary` (400). `param` מציין אותו.

### `invalid_category`

`GET /openapi.json?category=` מציין קטגוריה שאינה קיימת (400). `GET https://api.doitong.com/v1/categories` מציג את הקטגוריות.

### `invalid_cursor`

ה־`cursor` של קריאת רשימה אינו שייך לרשימה הזו (400). להתחיל מחדש ללא סמן.

### `invalid_idempotency_key`

הכותרת `Idempotency-Key` ריקה או ארוכה מ־255 תווים (400).

### `invalid_arguments`

לקריאת כלי MCP חסר ארגומנט או שיש בה ארגומנט פגום (MCP בלבד). `param` מציין את הארגומנט.

### `invalid_input`

קלט המודל אינו עובר אימות (422): פרמטר לא מוכר (ההודעה מציעה את השם התקף הקרוב ביותר),
פרמטר נדרש חסר, סוג שגוי, ערך מחוץ לרשימה או לטווח המותרים, או שניתנו גם השם הקנוני וגם
השם המקורי עם ערכים שונים. `param` הוא הפרמטר הראשון שגרם לבעיה, ו־`details` מציג את כולם.
לא נגבים קרדיטי API.

### `unsupported_file`

לקובץ יש סוג שאיננו מקבלים (422), למשל העלאה עם סיומת שאינה נתמכת, או `content_type`
שאינו תואם לסיומת.

### `invalid_webhook_url`

`webhook_url` אינו URL ציבורי מסוג `https://` (422). כתובות פרטיות, מקומיות וכתובות `http://` רגילות נדחות.

### `missing_api_key`

נקודת הקצה זקוקה למפתח API, אך לא נשלח מפתח (401).

### `invalid_api_key`

המפתח אינו מוכר, בוטל או פג תוקפו (401).

### `insufficient_scope`

למפתח חסרה ההרשאה שהקריאה הזו דורשת (403), למשל `models:run` להפעלה, או `models:read` לקריאת
בקשות והיתרה. ראו [אימות](https://doitong.com/developers/docs/authentication#scopes).

### `account_disabled`

החשבון נסגר או הושעה (403). המפתחות שלו אינם פועלים עוד.

### `not_found`

הנתיב אינו קיים (404).

### `model_not_found`

אין מודל ציבורי עם מזהה זה (404). יש להציג את המודלים באמצעות `GET https://api.doitong.com/v1/models`.

### `request_not_found`

אין בחשבון שלכם בקשה עם מזהה זה (404). בקשות של חשבונות אחרים לעולם אינן גלויות.

### `insufficient_credits`

**יתרת ה־API** של החשבון (קרדיטי API, 1,000 קרדיטי API = ⁨‏1 ‏$⁩ — לא הקרדיטים של אפליקציות Doitong) אינה מכסה את
מחיר הקריאה הזו (402). התגובה נשלחת לפני שחיוב כלשהו מתבצע. השגיאה כוללת `top_up_url`; יש להוסיף כסף
בכתובת [https://doitong.com/developers/dashboard#balance](https://doitong.com/developers/dashboard#balance) ולנסות שוב.

```json
{ "error": { "type": "insufficient_credits", "code": "insufficient_credits",
             "message": "This request costs 560 API credits ($0.56); the API balance is 120 API credits ($0.12). Top up at https://doitong.com/developers/dashboard#balance",
             "top_up_url": "https://doitong.com/developers/dashboard#balance", "doc_url": "https://doitong.com/developers/docs/errors#insufficient_credits" } }
```

### `budget_exceeded`

הקריאה תחרוג מהתקציב של מפתח ה־API עצמו בקרדיטי API (402). התקציב נקבע על ידי בעל המפתח; ניסיון חוזר לא יעזור
עד שבעל המפתח יגדיל אותו.

### `conflict`

הקריאה מתנגשת במצב הנוכחי של המשאב (409).

### `idempotency_mismatch`

ה־`Idempotency-Key` כבר שימש עם גוף בקשה אחר (409). יש להשתמש במפתח חדש לפעולה חדשה.

### `idempotency_in_progress`

בקשה עם אותו `Idempotency-Key` נוצרת כרגע (409). לנסות שוב בעוד רגע כדי לקבל אותה.

### `request_active`

הבקשה עדיין `queued` או `running`, ולכן עדיין אין לה קבצים למחיקה (409). יש למחוק אותם לאחר שתסתיים.

### `not_cancelable`

הבקשה כבר `succeeded` או `failed` ואי אפשר לבטל אותה (409).

### `rate_limited`

המפתח שלח יותר מדי בקשות בחלון הנוכחי (429). ראו את הכותרות `X-RateLimit-*` ו־`Retry-After`.

### `too_many_inflight`

בחשבון כבר יש 10 בקשות במצב `queued` או `running` (429). יש להתחיל את הבאה כאשר אחת מהן תסתיים.

### `upstream_error`

עורף המודל דחה את הבקשה או נכשל בעיבודה (502 בעת הפעלה, או `failed` עם קוד זה בבקשה). קרדיטי ה־API
מוחזרים. אם העורף עצמו דחה את הקלט, הקריאה מחזירה `422 invalid_input` עם ההודעה שלו במקום זאת.

### `upstream_lost`

עורף המודל אינו מכיר עוד את הבקשה, ולכן אף תוצאה לא תגיע. היא מסתיימת כ־`failed` עם קוד זה
(סוג `upstream_error`) ומקבלת החזר. יש להפעיל אותה שוב.

### `timeout`

הבקשה פעלה מעבר למגבלת הזמן שלה (15 דקות לתמונות, 60 לווידאו, 30 בכל מקרה אחר) ונעצרה. היא מסתיימת כ־
`failed` עם קוד זה ומקבלת החזר.

### `service_unavailable`

ה־API מושהה זמנית, או שתלות כגון העלאות קבצים אינה זמינה (503). לנסות שוב מאוחר יותר.

### `internal_error`

משהו השתבש בצד שלנו (500). לנסות שוב; אם הבעיה נמשכת, לפנות לתמיכה.

### `charge_failed`

לא ניתן היה לחייב את החשבון בגלל בעיה פנימית (500). הבקשה מסומנת כ־`failed`; לא נגבה דבר.
לנסות שוב.

### `pricing_unavailable`

מחיר המודל אינו מוגדר, ולכן אי אפשר לקבל הצעת מחיר או להפעיל אותו כרגע (500).