# Błędy

Każdy endpoint kończy się tak samo: statusem HTTP i jednym obiektem 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"
  }
}
```

| Pole | Znaczenie |
|---|---|
| `type` | Ogólna klasa błędu. Na tej podstawie zdecyduj, co zrobić. |
| `code` | Dokładna przyczyna, stabilna i czytelna maszynowo. Każdy kod ma poniżej własną sekcję; `doc_url` prowadzi do niej. |
| `message` | Zrozumiałe dla człowieka wyjaśnienie, bezpieczne do zapisania w logu lub wyświetlenia deweloperowi. |
| `param` | Błędny parametr danych wejściowych lub nagłówek, jeśli taki istnieje. |
| `details` | W przypadku błędów danych wejściowych każdy znaleziony problem: `[{ "param", "message" }]`. |
| `request_id` | Żądanie, którego dotyczy błąd, jeśli istnieje. |

Za wywołanie zwracające błąd nie jest pobierana opłata. Żądanie, które kończy się niepowodzeniem *po* zaakceptowaniu, zachowuje status
`failed`, zawiera `error: { "type", "code", "message" }` w obiekcie żądania i otrzymuje automatyczny zwrot.

## Typy

| Typ | Status HTTP | Co zrobić |
|---|---|---|
| `invalid_request` | 400, 413 lub 422 | Popraw żądanie. Ponowienie tego samego wywołania znów się nie powiedzie. |
| `authentication_error` | 401 | Wyślij prawidłowy klucz w `Authorization: Bearer <key>`. |
| `permission_error` | 403 | Użyj klucza z wymaganym zakresem uprawnień. |
| `not_found` | 404 | Sprawdź identyfikator modelu lub żądania. |
| `insufficient_credits` | 402 | Doładuj saldo API (`top_up_url` w błędzie). |
| `budget_exceeded` | 402 | Wykorzystano budżet tego klucza. Ostatecznie poproś właściciela klucza o jego zwiększenie. |
| `conflict` | 409 | Zasób nie jest w stanie pozwalającym na to wywołanie. |
| `rate_limited` | 429 | Odczekaj `Retry-After` sekund, a następnie ponów próbę. |
| `upstream_error` | 502 | Backend modelu nie zadziałał. Możesz bezpiecznie ponowić próbę z tym samym `Idempotency-Key`: operacja wykona się ponownie; opłata nie została pobrana. |
| `service_unavailable` | 503 | API jest wstrzymane lub niedostępna jest zależność. Spróbuj później. |
| `internal_error` | 500 | Błąd po naszej stronie. Ponów próbę; jeśli problem się utrzymuje, skontaktuj się z pomocą techniczną, podając czas i `request_id`. |

## Kody

### `invalid_request`

Ogólnie nieprawidłowe żądanie (400).

### `invalid_json`

Treść nie jest prawidłowym JSON-em (400).

### `invalid_body`

Treść jest prawidłowym JSON-em, ale nie jest obiektem; dane wejściowe modelu muszą być obiektem JSON (400).

### `body_too_large`

Treść jest większa niż 16 MB (413). Prześlij duże pliki i zamiast nich przekaż ich URL (zobacz [Pliki](https://doitong.com/developers/docs/files)).

### `invalid_parameter`

Parametr zapytania ma nieprawidłową wartość, na przykład `limit` poza zakresem od 1 do 100, `wait` nie jest liczbą, nieznany
`status` lub `category`, albo `storage` ma wartość inną niż `permanent` / `temporary` (400). `param` wskazuje ten parametr.

### `invalid_category`

`GET /openapi.json?category=` wskazuje kategorię, która nie istnieje (400). `GET https://api.doitong.com/v1/categories` wyświetla ich listę.

### `invalid_cursor`

`cursor` wywołania listy nie należy do tej listy (400). Zacznij ponownie bez kursora.

### `invalid_idempotency_key`

Nagłówek `Idempotency-Key` jest pusty lub dłuższy niż 255 znaków (400).

### `invalid_arguments`

Wywołanie narzędzia MCP zawiera brakujący lub nieprawidłowy argument (tylko MCP). `param` wskazuje argument.

### `invalid_input`

Dane wejściowe modelu nie przechodzą walidacji (422): nieznany parametr (komunikat sugeruje najbardziej zbliżoną prawidłową nazwę),
brak wymaganej wartości, nieprawidłowy typ, wartość spoza dozwolonej listy lub zakresu albo podano nazwę kanoniczną i
natywną z różnymi wartościami. `param` wskazuje pierwszy błędny parametr, a `details` zawiera wszystkie. Opłata nie jest pobierana.

### `unsupported_file`

Plik ma typ, którego nie akceptujemy (422), na przykład przesłano plik z nieobsługiwanym rozszerzeniem lub `content_type`
niezgodny z rozszerzeniem.

### `invalid_webhook_url`

`webhook_url` nie jest publicznym adresem URL `https://` (422). Adresy prywatne, lokalne i zwykłe `http://` są odrzucane.

### `missing_api_key`

Endpoint wymaga klucza API, ale go nie wysłano (401).

### `invalid_api_key`

Klucz jest nieznany, unieważniony lub wygasł (401).

### `insufficient_scope`

Klucz nie ma zakresu uprawnień wymaganego przez to wywołanie (403), na przykład `models:run` do uruchomienia lub `models:read` do odczytu
żądań i salda. Zobacz [Uwierzytelnianie](https://doitong.com/developers/docs/authentication#scopes).

### `account_disabled`

Konto jest zamknięte lub zawieszone (403). Jego klucze przestały działać.

### `not_found`

Ścieżka nie istnieje (404).

### `model_not_found`

Żaden publiczny model nie ma tego identyfikatora (404). Wyświetl modele za pomocą `GET https://api.doitong.com/v1/models`.

### `request_not_found`

Na koncie nie istnieje żądanie o tym identyfikatorze (404). Żądania innych kont nigdy nie są widoczne.

### `insufficient_credits`

**Saldo API** konta (kredyty API, 1000 kredytów API = 1 $ — nie kredyty aplikacji Doitong) nie pokrywa ceny tego wywołania (402). Odpowiedź jest wysyłana, zanim zostanie pobrana jakakolwiek opłata. Błąd zawiera `top_up_url`; dodaj środki pod adresem [https://doitong.com/developers/dashboard#balance](https://doitong.com/developers/dashboard#balance) i ponów próbę.

```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`

Wywołanie przekroczyłoby własny budżet klucza API w kredytach API (402). Budżet ustala właściciel klucza; ponowienie próby nie pomoże, dopóki go nie zwiększy.

### `conflict`

Wywołanie jest sprzeczne z bieżącym stanem zasobu (409).

### `idempotency_mismatch`

`Idempotency-Key` został już użyty z inną treścią (409). Użyj nowego klucza dla nowej operacji.

### `idempotency_in_progress`

Właśnie tworzone jest żądanie z tym samym `Idempotency-Key` (409). Za chwilę ponów próbę, aby je uzyskać.

### `request_active`

Żądanie nadal ma status `queued` lub `running`, więc nie ma jeszcze plików do usunięcia (409). Usuń je po zakończeniu żądania.

### `not_cancelable`

Żądanie ma już status `succeeded` lub `failed` i nie można go anulować (409).

### `rate_limited`

Klucz wykonał zbyt wiele żądań w bieżącym oknie (429). Zobacz nagłówki `X-RateLimit-*` i `Retry-After`.

### `too_many_inflight`

Konto ma już 10 żądań ze statusem `queued` lub `running` (429). Uruchom następne, gdy jedno z nich się zakończy.

### `upstream_error`

Backend modelu odrzucił żądanie lub nie zdołał go wykonać (502 podczas uruchamiania albo `failed` z tym kodem w żądaniu). Kredyty API są zwracane. Jeśli backend odrzucił same dane wejściowe, wywołanie zwraca `422 invalid_input` z odpowiednim komunikatem.

### `upstream_lost`

Backend modelu nie zna już żądania, więc wynik nigdy nie nadejdzie. Żądanie kończy się statusem `failed` z tym kodem
(typ `upstream_error`) i otrzymuje zwrot. Uruchom je ponownie.

### `timeout`

Żądanie trwało dłużej niż limit (15 minut dla obrazów, 60 dla wideo, 30 w pozostałych przypadkach) i zostało zatrzymane. Kończy się statusem
`failed` z tym kodem i otrzymuje zwrot.

### `service_unavailable`

API jest tymczasowo wstrzymane lub niedostępna jest zależność, na przykład przesyłanie plików (503). Spróbuj później.

### `internal_error`

Coś zepsuło się po naszej stronie (500). Ponów próbę; jeśli problem się utrzymuje, skontaktuj się z pomocą techniczną.

### `charge_failed`

Nie można obciążyć konta z powodu wewnętrznego problemu (500). Żądanie otrzymuje status `failed`; nic nie pobrano. Ponów próbę.

### `pricing_unavailable`

Cena modelu nie jest skonfigurowana, więc nie można jej teraz wyświetlić ani uruchomić modelu (500).