# פֿעלער

יעדער ענדפּוינט פֿעלט אויף דער זעלבער אופֿן: אַן 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` | די בקשה וואָס עס באַטרעפֿט, אויב ס׳איז דאָ איינער. |

גאָרנישט ווערט געצאָלט פֿאַר אַ רוף וואָס קערט צוריק אַ פֿעלער. אַ בקשה וואָס פֿעלט *נאָך* דעם ווי זי איז אָנגענומען געוואָרן, בלײַבט מיט סטאַטוס `failed`, טראָגט `error: { "type", "code", "message" }` אינעם בקשה־אָביעקט, און ווערט אויטאָמאַטיש צוריקגעצאָלט.

## טיפּן

| טיפּ | HTTP סטאַטוס | וואָס צו טאָן |
|---|---|---|
| `invalid_request` | 400, 413 אָדער 422 | פֿאַרריכט די בקשה. דער זעלבער ווידער־רוף פֿעלט ווידער. |
| `authentication_error` | 401 | שיקט אַ גילטיקן שליסל אין `Authorization: Bearer <key>`. |
| `permission_error` | 403 | ניצט אַ שליסל מיטן נייטיקן scope. |
| `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). הייבט אָן ווידער אָן cursor.

### `invalid_idempotency_key`

דער `Idempotency-Key` העדער איז ליידיק אָדער לענגער ווי 255 אותיות (400).

### `invalid_arguments`

אַן MCP־tool רוף האָט אַ פעלנדיקן אָדער פֿעלערדיקן אַרגומענט (בלויז MCP). `param` באַצייכנט דעם אַרגומענט.

### `invalid_input`

די מאָדעל־אַרײַנגעבונג גייט נישט דורך דער וואַלידאַציע (422): אַן אומבאַקאַנטער פּאַראַמעטער (די מעלדונג פֿאָרשלאָגט דעם נאָענטסטן גילטיקן נאָמען), אַ פעלנדיקער נייטיקער פּאַראַמעטער, אַן אומריכטיקער טיפּ, אַ ווערט אַרויס פֿון דער ערלויבטער ליסטע אָדער ריי, אָדער ביידע דער קאַנאָנישער און געבוירענער נאָמען מיט פֿאַרשידענע ווערטן. `param` איז דער ערשטער שולדיקער פּאַראַמעטער און `details` ליסטעט זיי אַלע. גאָרנישט ווערט געצאָלט.

### `unsupported_file`

אַ פֿײַל האָט אַ טיפּ וואָס מיר אָננעמען נישט (422), למשל אַן אַרויפֿגעלאָדענע פֿײַל מיט אַן נישט־געשטיצטער עקסטענסיע, אָדער אַ `content_type` וואָס שטימט נישט מיט דער עקסטענסיע.

### `invalid_webhook_url`

`webhook_url` איז נישט קיין פּובליקע `https://` URL (422). פּריוואַטע, לאָקאַלע און פּשוטע `http://` אַדרעסן ווערן אָפּגעוויזן.

### `missing_api_key`

דער ענדפּוינט דאַרף אַן API שליסל און קיין שליסל איז נישט געשיקט געוואָרן (401).

### `invalid_api_key`

דער שליסל איז אומבאַקאַנט, אָפּגערופֿן אָדער אויסגעגאַנגען (401).

### `insufficient_scope`

דער שליסל האָט נישט דעם 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).