# Virheet

Jokainen päätepiste epäonnistuu samalla tavalla: HTTP-tila ja yksi JSON-kuori.

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

| Kenttä | Merkitys |
|---|---|
| `type` | Virheen yleinen luokka. Päätä tämän perusteella, mitä tehdä. |
| `code` | Tarkka syy, vakaa ja koneellisesti luettava. Jokaisella koodilla on alla oma osionsa; `doc_url` linkittää siihen. |
| `message` | Ihmiselle luettava selitys, jonka voi turvallisesti kirjata lokiin tai näyttää kehittäjälle. |
| `param` | Virheen aiheuttanut syöteparametri tai otsake, jos sellainen on. |
| `details` | Syötevirheissä kaikki havaitut ongelmat: `[{ "param", "message" }]`. |
| `request_id` | Pyyntö, jota virhe koskee, jos sellainen on. |

Virheen palauttavasta kutsusta ei veloiteta mitään. Pyyntö, joka epäonnistuu *sen jälkeen*, kun se on hyväksytty, säilyttää tilan
`failed`, sisältää pyyntöobjektissa kentän `error: { "type", "code", "message" }`, ja siitä tehdään automaattisesti hyvitys.

## Tyypit

| Tyyppi | HTTP-tila | Toimi näin |
|---|---|---|
| `invalid_request` | 400, 413 tai 422 | Korjaa pyyntö. Saman kutsun uudelleenyritys epäonnistuu taas. |
| `authentication_error` | 401 | Lähetä kelvollinen avain otsakkeessa `Authorization: Bearer <key>`. |
| `permission_error` | 403 | Käytä avainta, jolla on tarvittava käyttöoikeusalue. |
| `not_found` | 404 | Tarkista mallin tunniste tai pyynnön tunniste. |
| `insufficient_credits` | 402 | Tee API-saldon lisäys (`top_up_url` virheessä). |
| `budget_exceeded` | 402 | Avaimen oma budjetti on käytetty. Lopullinen ratkaisu: pyydä avaimen omistajaa korottamaan sitä. |
| `conflict` | 409 | Resurssi ei ole tilassa, joka sallii tämän kutsun. |
| `rate_limited` | 429 | Odota `Retry-After` sekuntia ja yritä sitten uudelleen. |
| `upstream_error` | 502 | Mallin taustajärjestelmä epäonnistui. Uudelleenyritys samalla `Idempotency-Key`-avaimella on turvallista: ajo suoritetaan uudelleen eikä sinua veloitettu. |
| `service_unavailable` | 503 | API on keskeytetty tai riippuvuus ei ole käytettävissä. Yritä myöhemmin uudelleen. |
| `internal_error` | 500 | Virhe palvelussamme. Yritä uudelleen; jos ongelma jatkuu, ota yhteyttä tukeen ja ilmoita aika sekä `request_id`. |

## Koodit

### `invalid_request`

Yleinen virheellinen pyyntö (400).

### `invalid_json`

Runko ei ole kelvollista JSONia (400).

### `invalid_body`

Runko on kelvollista JSONia, mutta ei objekti; mallin syötteen on oltava JSON-objekti (400).

### `body_too_large`

Runko on suurempi kuin 16 MB (413). Lataa suuret tiedostot ja välitä niiden URL-osoite sen sijaan (katso [Tiedostot](https://doitong.com/developers/docs/files)).

### `invalid_parameter`

Kyselyparametrin arvo on väärä, esimerkiksi `limit` on alueen 1–100 ulkopuolella, `wait` ei ole luku, `status` tai `category` on tuntematon tai `storage` on jokin muu kuin `permanent` / `temporary` (400). `param` ilmoittaa sen nimen.

### `invalid_category`

`GET /openapi.json?category=` ilmoittaa luokan, jota ei ole (400). `GET https://api.doitong.com/v1/categories` luettelee luokat.

### `invalid_cursor`

Luettelokutsun `cursor` ei kuulu tähän luetteloon (400). Aloita uudelleen ilman kohdistinta.

### `invalid_idempotency_key`

`Idempotency-Key`-otsake on tyhjä tai yli 255 merkkiä pitkä (400).

### `invalid_arguments`

MCP-työkalukutsusta puuttuu argumentti tai se on virheellinen (vain MCP). `param` ilmoittaa argumentin nimen.

### `invalid_input`

Mallin syöte ei läpäise validointia (422): tuntematon parametri (viesti ehdottaa lähintä kelvollista nimeä), puuttuva pakollinen parametri, väärä tyyppi, sallittujen arvojen tai alueen ulkopuolinen arvo tai sekä kanoninen että natiivi nimi annettuna eri arvoilla. `param` on ensimmäinen virheellinen parametri ja `details` luettelee ne kaikki.
Mitään ei veloiteta.

### `unsupported_file`

Tiedoston tyyppiä ei hyväksytä (422), esimerkiksi tiedosto käyttää tukematonta päätettä tai `content_type` ei vastaa päätettä.

### `invalid_webhook_url`

`webhook_url` ei ole julkinen `https://`-URL-osoite (422). Yksityiset, paikalliset ja tavalliset `http://`-osoitteet hylätään.

### `missing_api_key`

Päätepiste tarvitsee API-avaimen, mutta sitä ei lähetetty (401).

### `invalid_api_key`

Avain on tuntematon, peruttu tai vanhentunut (401).

### `insufficient_scope`

Avaimella ei ole tämän kutsun tarvitsemaa käyttöoikeusaluetta (403), esimerkiksi `models:run` ajoa varten tai `models:read` pyyntöjen ja saldon lukemista varten. Katso [Todennus](https://doitong.com/developers/docs/authentication#scopes).

### `account_disabled`

Tili on suljettu tai jäädytetty (403). Sen avaimet eivät enää toimi.

### `not_found`

Polkua ei ole (404).

### `model_not_found`

Tällä tunnisteella ei ole julkista mallia (404). Luettele mallit komennolla `GET https://api.doitong.com/v1/models`.

### `request_not_found`

Tililläsi ei ole tällä tunnisteella olevaa pyyntöä (404). Muiden tilien pyyntöjä ei koskaan näytetä.

### `insufficient_credits`

Tilin **API-saldo** (API-krediittiä, 1 000 API-krediittiä = 1 $ — ei Doitong-sovellusten krediittejä) ei riitä tämän kutsun hintaan (402). Vastaus lähetetään ennen veloitusta. Virhe sisältää `top_up_url`-osoitteen; lisää rahaa osoitteessa [https://doitong.com/developers/dashboard#balance](https://doitong.com/developers/dashboard#balance) ja yritä uudelleen.

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

Kutsu ylittäisi API-avaimen oman budjetin API-krediitteinä (402). Avaimen omistaja määrittää budjetin; uudelleenyritys ei auta, ennen kuin hän korottaa sitä.

### `conflict`

Kutsu on ristiriidassa resurssin nykyisen tilan kanssa (409).

### `idempotency_mismatch`

`Idempotency-Key`-avainta on jo käytetty eri rungon kanssa (409). Käytä uutta avainta uuteen toimintaan.

### `idempotency_in_progress`

Samalla `Idempotency-Key`-avaimella luodaan juuri nyt pyyntöä (409). Yritä hetken kuluttua uudelleen saadaksesi sen.

### `request_active`

Pyyntö on yhä tilassa `queued` tai `running`, joten sillä ei ole vielä poistettavia tiedostoja (409). Poista ne, kun pyyntö on valmis.

### `not_cancelable`

Pyyntö on jo tilassa `succeeded` tai `failed`, eikä sitä voi peruuttaa (409).

### `rate_limited`

Avain teki nykyisen aikajakson aikana liian monta pyyntöä (429). Katso `X-RateLimit-*`- ja `Retry-After`-otsakkeet.

### `too_many_inflight`

Tilillä on jo 10 pyyntöä tilassa `queued` tai `running` (429). Käynnistä seuraava, kun yksi niistä valmistuu.

### `upstream_error`

Mallin taustajärjestelmä hylkäsi pyynnön tai epäonnistui sen käsittelyssä (ajossa 502 tai pyyntöobjektissa `failed` tällä koodilla). API-krediiteistä tehdään hyvitys. Jos taustajärjestelmä hylkäsi syötteen itse, kutsu palauttaa sen sijaan viestin sisältävän `422 invalid_input` -virheen.

### `upstream_lost`

Mallin taustajärjestelmä ei enää tunne pyyntöä, joten tulosta ei koskaan saada. Pyyntö päättyy tilaan `failed` tällä koodilla (tyyppi `upstream_error`) ja siitä tehdään hyvitys. Suorita se uudelleen.

### `timeout`

Pyyntö kesti pidempään kuin sen aikaraja (kuville 15 minuuttia, videolle 60 ja muille 30 minuuttia), joten se pysäytettiin. Se päättyy tällä koodilla tilaan `failed`, ja siitä tehdään hyvitys.

### `service_unavailable`

API on tilapäisesti keskeytetty tai jokin riippuvuus, kuten tiedostojen lataus, ei ole käytettävissä (503). Yritä myöhemmin uudelleen.

### `internal_error`

Palvelussamme tapahtui virhe (500). Yritä uudelleen; jos ongelma jatkuu, ota yhteyttä tukeen.

### `charge_failed`

Tililtä ei voitu veloittaa sisäisen ongelman vuoksi (500). Pyyntö merkitään tilaan `failed`; mitään ei veloitettu. Yritä uudelleen.

### `pricing_unavailable`

Mallin hintaa ei ole määritetty, joten sitä ei voi tällä hetkellä hinnoitella tai suorittaa (500).