# Pogreške

Svaka krajnja točka ne uspije na isti način: HTTP status i jedan JSON omotač.

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

| Polje | Značenje |
|---|---|
| `type` | Šira klasa pogreške. Na temelju ovoga odlučite što učiniti. |
| `code` | Točan razlog, stabilan i strojno čitljiv. Svaki kod ima odjeljak u nastavku; `doc_url` vodi na njega. |
| `message` | Objašnjenje čitljivo ljudima, sigurno za zapisivanje ili prikaz programeru. |
| `param` | Ulazni parametar ili zaglavlje koje uzrokuje problem, ako postoji. |
| `details` | Za ulazne pogreške, svaki pronađeni problem: `[{ "param", "message" }]`. |
| `request_id` | Zahtjev na koji se odnosi, ako postoji. |

Poziv koji vrati pogrešku ne naplaćuje se. Zahtjev koji ne uspije *nakon* prihvaćanja zadržava status
`failed`, na objektu zahtjeva sadrži `error: { "type", "code", "message" }` i automatski se vraća novac.

## Vrste

| Vrsta | HTTP status | Što učiniti |
|---|---|---|
| `invalid_request` | 400, 413 ili 422 | Ispravite zahtjev. Ponovni pokušaj istog poziva ponovno neće uspjeti. |
| `authentication_error` | 401 | Pošaljite valjani ključ u `Authorization: Bearer <key>`. |
| `permission_error` | 403 | Upotrijebite ključ s potrebnim opsegom. |
| `not_found` | 404 | Provjerite id modela ili id zahtjeva. |
| `insufficient_credits` | 402 | Nadoplatite API stanje (`top_up_url` u pogrešci). |
| `budget_exceeded` | 402 | Vlastiti proračun ključa je potrošen. Konačno rješenje: zatražite od vlasnika ključa da ga poveća. |
| `conflict` | 409 | Resurs nije u stanju koje dopušta ovaj poziv. |
| `rate_limited` | 429 | Pričekajte `Retry-After` sekundi, zatim pokušajte ponovno. |
| `upstream_error` | 502 | Pozadina modela nije uspjela. Sigurno je pokušati ponovno s istim `Idempotency-Key`: pokreće se iznova; niste naplaćeni. |
| `service_unavailable` | 503 | API je pauziran ili ovisnost nije dostupna. Pokušajte ponovno kasnije. |
| `internal_error` | 500 | Naša pogreška. Pokušajte ponovno; ako se ponavlja, kontaktirajte podršku s vremenom i `request_id`. |

## Kodovi

### `invalid_request`

Općenito neispravan zahtjev (400).

### `invalid_json`

Tijelo nije valjani JSON (400).

### `invalid_body`

Tijelo je valjani JSON, ali nije objekt; ulaz modela mora biti JSON objekt (400).

### `body_too_large`

Tijelo je veće od 16 MB (413). Prenesite velike datoteke i umjesto toga proslijedite njihov URL (pogledajte [Datoteke](https://doitong.com/developers/docs/files)).

### `invalid_parameter`

Parametar upita ima pogrešnu vrijednost, primjerice `limit` izvan raspona 1 do 100, `wait` nije broj, nepoznat
`status` ili `category`, ili `storage` različit od `permanent` / `temporary` (400). `param` navodi koji je to parametar.

### `invalid_category`

`GET /openapi.json?category=` navodi kategoriju koja ne postoji (400). `GET https://api.doitong.com/v1/categories` prikazuje popis kategorija.

### `invalid_cursor`

`cursor` poziva za popis ne pripada ovom popisu (400). Počnite ponovno bez kursora.

### `invalid_idempotency_key`

Zaglavlje `Idempotency-Key` prazno je ili dulje od 255 znakova (400).

### `invalid_arguments`

Pozivu MCP alata nedostaje argument ili je argument neispravan (samo MCP). `param` navodi argument.

### `invalid_input`

Ulaz modela ne prolazi provjeru valjanosti (422): nepoznat parametar (poruka predlaže najbliži valjani naziv),
obavezan parametar koji nedostaje, pogrešna vrsta, vrijednost izvan dopuštenog popisa ili raspona, ili su navedeni i kanonski i
izvorni naziv s različitim vrijednostima. `param` je prvi problematični parametar, a `details` navodi sve takve parametre.
Ništa se ne naplaćuje.

### `unsupported_file`

Datoteka ima vrstu koju ne prihvaćamo (422), primjerice prijenos s nepodržanim nastavkom ili `content_type`
koji ne odgovara nastavku.

### `invalid_webhook_url`

`webhook_url` nije javni `https://` URL (422). Privatne, lokalne i obične `http://` adrese odbijaju se.

### `missing_api_key`

Krajnja točka zahtijeva API ključ, ali nijedan nije poslan (401).

### `invalid_api_key`

Ključ je nepoznat, opozvan ili je istekao (401).

### `insufficient_scope`

Ključ nema opseg potreban za ovaj poziv (403), primjerice `models:run` za pokretanje ili `models:read` za čitanje
zahtjeva i stanja. Pogledajte [Autentifikacija](https://doitong.com/developers/docs/authentication#scopes).

### `account_disabled`

Račun je zatvoren ili suspendiran (403). Njegovi ključevi više ne rade.

### `not_found`

Putanja ne postoji (404).

### `model_not_found`

Nijedan javni model nema ovaj id (404). Popis modela dohvatite s `GET https://api.doitong.com/v1/models`.

### `request_not_found`

U vašem računu ne postoji zahtjev s ovim id-jem (404). Zahtjevi drugih računa nikad nisu vidljivi.

### `insufficient_credits`

**API stanje** računa (API krediti, 1.000 API kredita = 1 $ — ne krediti aplikacija Doitong) ne pokriva
cijenu ovog poziva (402). Odgovor se šalje prije bilo kakve naplate. Pogreška sadrži `top_up_url`; dodajte novac
na [https://doitong.com/developers/dashboard#balance](https://doitong.com/developers/dashboard#balance) i pokušajte ponovno.

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

Poziv bi premašio vlastiti proračun API ključa u API kreditima (402). Proračun postavlja vlasnik ključa; ponovni pokušaj ne
pomaže dok ga vlasnik ne poveća.

### `conflict`

Poziv je u sukobu s trenutačnim stanjem resursa (409).

### `idempotency_mismatch`

`Idempotency-Key` je već upotrijebljen s drugim tijelom (409). Za novu operaciju upotrijebite novi ključ.

### `idempotency_in_progress`

Zahtjev s istim `Idempotency-Key` trenutačno se izrađuje (409). Pokušajte ponovno za trenutak da biste ga dohvatili.

### `request_active`

Zahtjev je još `queued` ili `running`, pa još nema datoteka za brisanje (409). Obrišite ih kad završi.

### `not_cancelable`

Zahtjev je već `succeeded` ili `failed` i ne može se otkazati (409).

### `rate_limited`

Ključ je u trenutačnom prozoru poslao previše zahtjeva (429). Pogledajte zaglavlja `X-RateLimit-*` i `Retry-After`.

### `too_many_inflight`

Račun već ima 10 zahtjeva u stanju `queued` ili `running` (429). Pokrenite sljedeći kad jedan od njih završi.

### `upstream_error`

Pozadina modela odbila je zahtjev ili nije uspjela obraditi ga (502 pri pokretanju ili `failed` s ovim kodom na zahtjevu). API krediti se
vraćaju. Ako je sama pozadina odbila ulaz, poziv vraća `422 invalid_input` s pripadajućom porukom.

### `upstream_lost`

Pozadina modela više ne prepoznaje zahtjev, pa rezultat nikad neće stići. Završava kao `failed` s ovim kodom
(vrsta `upstream_error`) i sredstva se vraćaju. Pokrenite ga ponovno.

### `timeout`

Zahtjev je trajao dulje od ograničenja (15 minuta za slike, 60 za video, 30 u ostalim slučajevima) i zaustavljen je. Završava kao
`failed` s ovim kodom i sredstva se vraćaju.

### `service_unavailable`

API je privremeno pauziran ili ovisnost, poput prijenosa datoteka, nije dostupna (503). Pokušajte ponovno kasnije.

### `internal_error`

Nešto se pokvarilo na našoj strani (500). Pokušajte ponovno; ako se ponavlja, kontaktirajte podršku.

### `charge_failed`

Račun se nije mogao naplatiti zbog internog problema (500). Zahtjev je označen kao `failed`; ništa nije uzeto. Pokušajte ponovno.

### `pricing_unavailable`

Cijena modela nije konfigurirana pa je trenutačno nije moguće navesti ni pokrenuti model (500).