# Napake

Vsaka končna točka odpove na enak način: s kodo stanja HTTP in enim ovojem 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"
  }
}
```

| Polje | Pomen |
|---|---|
| `type` | Širši razred napake. Na podlagi tega določite, kaj storiti. |
| `code` | Natančen razlog, stabilen in strojno berljiv. Vsaka koda ima spodaj svoj razdelek; `doc_url` vodi do njega. |
| `message` | Razlaga, berljiva človeku, primerna za beleženje ali prikaz razvijalcu. |
| `param` | Vhodni parameter ali glava, ki povzroča napako, če obstaja. |
| `details` | Pri vhodnih napakah vsaka najdena težava: `[{ "param", "message" }]`. |
| `request_id` | Zahteva, na katero se nanaša, če obstaja. |

Za klic, ki vrne napako, se nič ne zaračuna. Zahteva, ki ne uspe *po* sprejetju, ohrani stanje
`failed`, na objektu zahteve vsebuje `error: { "type", "code", "message" }` in se samodejno povrne.

## Vrste

| Vrsta | Stanje HTTP | Kaj storiti |
|---|---|---|
| `invalid_request` | 400, 413 ali 422 | Popravite zahtevo. Ponovni poskus istega klica bo znova neuspešen. |
| `authentication_error` | 401 | Pošljite veljaven ključ v `Authorization: Bearer <key>`. |
| `permission_error` | 403 | Uporabite ključ z zahtevanim obsegom. |
| `not_found` | 404 | Preverite ID modela ali ID zahteve. |
| `insufficient_credits` | 402 | Izvedite dopolnitev dobroimetja API (`top_up_url` v napaki). |
| `budget_exceeded` | 402 | Proračun ključa je porabljen. Končna rešitev: prosite lastnika ključa, naj ga poveča. |
| `conflict` | 409 | Vir ni v stanju, ki omogoča ta klic. |
| `rate_limited` | 429 | Počakajte `Retry-After` sekund in nato poskusite znova. |
| `upstream_error` | 502 | Zaledje modela ni uspelo. Ponovni poskus z istim `Idempotency-Key` je varen: izvedel se bo znova; zaračunano vam ni bilo. |
| `service_unavailable` | 503 | API je začasno zaustavljen ali odvisnost ni na voljo. Poskusite pozneje. |
| `internal_error` | 500 | Napaka na naši strani. Poskusite znova; če se ponavlja, se ob času in z `request_id` obrnite na podporo. |

## Kode

### `invalid_request`

Splošno nepravilno oblikovana zahteva (400).

### `invalid_json`

Telo ni veljaven JSON (400).

### `invalid_body`

Telo je veljaven JSON, vendar ni objekt; vhod modela mora biti objekt JSON (400).

### `body_too_large`

Telo je večje od 16 MB (413). Naložite velike datoteke in namesto tega posredujte njihov URL (glejte [Datoteke](https://doitong.com/developers/docs/files)).

### `invalid_parameter`

Parameter poizvedbe ima napačno vrednost, na primer `limit` zunaj razpona 1–100, `wait` ni število, neznan
`status` ali `category` oziroma `storage`, ki ni `permanent` / `temporary` (400). `param` ga poimenuje.

### `invalid_category`

`GET /openapi.json?category=` navaja kategorijo, ki ne obstaja (400). `GET https://api.doitong.com/v1/categories` jih izpiše.

### `invalid_cursor`

`cursor` klica za seznam ne pripada temu seznamu (400). Začnite znova brez kazalca.

### `invalid_idempotency_key`

Glava `Idempotency-Key` je prazna ali daljša od 255 znakov (400).

### `invalid_arguments`

Klic orodja MCP ima manjkajoč ali nepravilno oblikovan argument (samo MCP). `param` poimenuje argument.

### `invalid_input`

Vhod modela ne prestane preverjanja (422): neznan parameter (sporočilo predlaga najbližje veljavno ime),
manjkajoč zahtevan parameter, napačen tip, vrednost zunaj dovoljenega seznama ali razpona oziroma hkraten vnos kanoničnega in
izvornega imena z različnima vrednostma. `param` je prvi sporni parameter, `details` pa navede vse.
Nič se ne zaračuna.

### `unsupported_file`

Datoteka ima vrsto, ki je ne sprejemamo (422), na primer naložena datoteka z nepodprto pripono ali `content_type`,
ki se ne ujema s pripono.

### `invalid_webhook_url`

`webhook_url` ni javni URL `https://` (422). Zasebni, lokalni in navadni naslovi `http://` so zavrnjeni.

### `missing_api_key`

Končna točka potrebuje ključ API, vendar ta ni bil poslan (401).

### `invalid_api_key`

Ključ je neznan, preklican ali potekel (401).

### `insufficient_scope`

Ključ nima obsega, ki ga ta klic potrebuje (403), na primer `models:run` za zagon ali `models:read` za branje
zahtev in stanja. Glejte [Preverjanje pristnosti](https://doitong.com/developers/docs/authentication#scopes).

### `account_disabled`

Račun je zaprt ali začasno onemogočen (403). Njegovi ključi ne delujejo več.

### `not_found`

Pot ne obstaja (404).

### `model_not_found`

Javni model s tem ID-jem ne obstaja (404). Modele izpišete z `GET https://api.doitong.com/v1/models`.

### `request_not_found`

V vašem računu ne obstaja nobena zahteva s tem ID-jem (404). Zahteve drugih računov niso nikoli vidne.

### `insufficient_credits`

**Stanje API** računa (krediti API, 1000 API kreditov = 1 $ — ne krediti aplikacij Doitong) ne pokriva
cene tega klica (402). Odgovor je poslan, preden se kar koli zaračuna. Napaka vsebuje `top_up_url`; sredstva dodajte
na [https://doitong.com/developers/dashboard#balance](https://doitong.com/developers/dashboard#balance) in poskusite znova.

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

Klic bi presegel lasten proračun ključa API v kreditih API (402). Proračun določi lastnik ključa; ponovni poskus ne
pomaga, dokler ga lastnik ne poveča.

### `conflict`

Klic je v nasprotju s trenutnim stanjem vira (409).

### `idempotency_mismatch`

`Idempotency-Key` je bil že uporabljen z drugim telesom (409). Za novo dejanje uporabite nov ključ.

### `idempotency_in_progress`

Zahteva z istim `Idempotency-Key` se trenutno ustvarja (409). Čez trenutek poskusite znova, da jo pridobite.

### `request_active`

Zahteva je še vedno `queued` ali `running`, zato še nima datotek za brisanje (409). Izbrišite jih, ko se konča.

### `not_cancelable`

Zahteva je že `succeeded` ali `failed` in je ni mogoče preklicati (409).

### `rate_limited`

Ključ je v trenutnem oknu poslal preveč zahtev (429). Glejte glavi `X-RateLimit-*` in `Retry-After`.

### `too_many_inflight`

Račun že ima 10 zahtev `queued` ali `running` (429). Naslednjo začnite, ko se ena od njih konča.

### `upstream_error`

Zaledje modela je zahtevo zavrnilo ali ni uspelo (502 pri zagonu oziroma `failed` s to kodo na zahtevi). Krediti API se
povrnejo. Če je zaledje samo zavrnilo vhod, klic vrne `422 invalid_input` z ustreznim sporočilom.

### `upstream_lost`

Zaledje modela zahteve ne pozna več, zato rezultat ne bo nikoli prispel. Konča se kot `failed` s to kodo
(vrsta `upstream_error`) in se povrne. Zaženite jo znova.

### `timeout`

Zahteva je tekla dlje od omejitve (15 minut za slike, 60 za video, sicer 30) in je bila ustavljena. Konča se kot
`failed` s to kodo in se povrne.

### `service_unavailable`

API je začasno zaustavljen ali odvisnost, kot so nalaganja datotek, ni na voljo (503). Poskusite pozneje.

### `internal_error`

Na naši strani je prišlo do napake (500). Poskusite znova; če se ponavlja, se obrnite na podporo.

### `charge_failed`

Računa ni bilo mogoče bremeniti zaradi notranje težave (500). Zahteva je označena kot `failed`; nič ni bilo odvzeto. Poskusite znova.

### `pricing_unavailable`

Cena modela ni nastavljena, zato je trenutno ni mogoče prikazati ali izvesti (500).