# Fejl

Alle endpoints fejler på samme måde: en HTTP-status og én JSON-kuvert.

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

| Felt | Betydning |
|---|---|
| `type` | Fejlens overordnede klasse. Beslut, hvad der skal gøres, ud fra dette. |
| `code` | Den præcise årsag, stabil og maskinlæsbar. Hver kode har et afsnit nedenfor; `doc_url` linker til det. |
| `message` | Læsevenlig forklaring, som er sikker at logge eller vise til en udvikler. |
| `param` | Den input-parameter eller header, der er årsag til fejlen, når der er en. |
| `details` | Ved inputfejl alle fundne problemer: `[{ "param", "message" }]`. |
| `request_id` | Den anmodning, det vedrører, når der findes en. |

Der opkræves ikke noget for et kald, der returnerer en fejl. En anmodning, der fejler *efter* at den er accepteret, beholder status
`failed`, indeholder `error: { "type", "code", "message" }` på anmodningsobjektet og tilbagebetales automatisk.

## Typer

| Type | HTTP-status | Hvad skal der gøres |
|---|---|---|
| `invalid_request` | 400, 413 eller 422 | Ret anmodningen. Hvis det samme kald prøves igen, fejler det igen. |
| `authentication_error` | 401 | Send en gyldig nøgle i `Authorization: Bearer <key>`. |
| `permission_error` | 403 | Brug en nøgle med det nødvendige scope. |
| `not_found` | 404 | Kontrollér model-id'et eller anmodnings-id'et. |
| `insufficient_credits` | 402 | Foretag optankning af API-saldoen (`top_up_url` i fejlen). |
| `budget_exceeded` | 402 | Nøglens eget budget er opbrugt. Endelig løsning: bed nøgleejeren om at hæve det. |
| `conflict` | 409 | Ressourcen er ikke i en tilstand, der tillader dette kald. |
| `rate_limited` | 429 | Vent `Retry-After` sekunder, og prøv derefter igen. |
| `upstream_error` | 502 | Modelbackendenden fejlede. Det er sikkert at prøve igen med den samme `Idempotency-Key`: den køres igen, og du blev ikke opkrævet. |
| `service_unavailable` | 503 | API'et er sat på pause, eller en afhængighed er nede. Prøv igen senere. |
| `internal_error` | 500 | En fejl hos os. Prøv igen; kontakt support med tidspunktet og `request_id`, hvis det fortsætter. |

## Koder

### `invalid_request`

Generisk ugyldig anmodning (400).

### `invalid_json`

Brødteksten er ikke gyldig JSON (400).

### `invalid_body`

Brødteksten er gyldig JSON, men ikke et objekt; modelinput skal være et JSON-objekt (400).

### `body_too_large`

Brødteksten er større end 16 MB (413). Upload store filer, og send deres URL i stedet (se [Filer](https://doitong.com/developers/docs/files)).

### `invalid_parameter`

En query-parameter har en forkert værdi, f.eks. `limit` uden for 1 til 100, `wait` er ikke et tal, en ukendt
`status` eller `category`, eller `storage` er andet end `permanent` / `temporary` (400). `param` angiver den.

### `invalid_category`

`GET /openapi.json?category=` angiver en kategori, der ikke findes (400). `GET https://api.doitong.ru/v1/categories` viser dem.

### `invalid_cursor`

`cursor` i et listekald hører ikke til denne liste (400). Start igen uden en cursor.

### `invalid_idempotency_key`

Headeren `Idempotency-Key` er tom eller længere end 255 tegn (400).

### `invalid_arguments`

Et MCP-værktøjskald har et manglende eller forkert formateret argument (kun MCP). `param` angiver argumentet.

### `invalid_input`

Modelinputtet består ikke valideringen (422): en ukendt parameter (meddelelsen foreslår det nærmeste gyldige navn),
en manglende obligatorisk parameter, en forkert type, en værdi uden for den tilladte liste eller det tilladte interval, eller både det kanoniske og det
native navn angivet med forskellige værdier. `param` er den første problematiske parameter, og `details` viser dem alle.
Der opkræves ikke noget.

### `unsupported_file`

En fil har en type, vi ikke accepterer (422), f.eks. en upload med en filendelse, der ikke understøttes, eller en `content_type`,
der ikke passer til filendelsen.

### `invalid_webhook_url`

`webhook_url` er ikke en offentlig `https://`-URL (422). Private, lokale og almindelige `http://`-adresser afvises.

### `missing_api_key`

Endpointet kræver en API-nøgle, men ingen blev sendt (401).

### `invalid_api_key`

Nøglen er ukendt, tilbagekaldt eller udløbet (401).

### `insufficient_scope`

Nøglen mangler det scope, som dette kald kræver (403), f.eks. `models:run` ved en kørsel eller `models:read` for at læse
anmodninger og saldoen. Se [Godkendelse](https://doitong.com/developers/docs/authentication#scopes).

### `account_disabled`

Kontoen er lukket eller suspenderet (403). Dens nøgler virker ikke længere.

### `not_found`

Stien findes ikke (404).

### `model_not_found`

Ingen offentlig model har dette id (404). Vis modeller med `GET https://api.doitong.ru/v1/models`.

### `request_not_found`

Der findes ingen anmodning med dette id på din konto (404). Anmodninger fra andre konti er aldrig synlige.

### `insufficient_credits`

Kontoens **API-saldo** (API-kreditter, 1.000 API-kreditter = 1 $ — ikke kreditterne i Doitong-apps) dækker ikke
prisen for dette kald (402). Svaret sendes, før der opkræves noget. Fejlen indeholder `top_up_url`; tilføj penge
på [https://doitong.ru/developers/dashboard#balance](https://doitong.ru/developers/dashboard#balance), og prøv igen.

```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.ru/developers/dashboard#balance",
             "top_up_url": "https://doitong.ru/developers/dashboard#balance", "doc_url": "https://doitong.com/developers/docs/errors#insufficient_credits" } }
```

### `budget_exceeded`

Kaldet ville overskride API-nøglens eget budget i API-kreditter (402). Budgettet fastsættes af nøgleejeren; det hjælper ikke at prøve igen,
før ejeren hæver det.

### `conflict`

Kaldet er i konflikt med ressourcens aktuelle tilstand (409).

### `idempotency_mismatch`

`Idempotency-Key` blev allerede brugt med en anden brødtekst (409). Brug en ny nøgle til en ny handling.

### `idempotency_in_progress`

En anmodning med den samme `Idempotency-Key` oprettes lige nu (409). Prøv igen om et øjeblik for at hente den.

### `request_active`

Anmodningen er stadig `queued` eller `running`, så den har endnu ingen filer, der kan slettes (409). Slet dem, når den er færdig.

### `not_cancelable`

Anmodningen er allerede `succeeded` eller `failed` og kan ikke annulleres (409).

### `rate_limited`

Nøglen sendte for mange anmodninger i det aktuelle tidsvindue (429). Se headerne `X-RateLimit-*` og `Retry-After`.

### `too_many_inflight`

Kontoen har allerede 10 anmodninger, der er `queued` eller `running` (429). Start den næste, når en af dem er færdig.

### `upstream_error`

Modelbackendenden afviste eller kunne ikke behandle anmodningen (502 ved kørsel eller `failed` med denne kode på anmodningen). API-kreditterne
tilbagebetales. Hvis backendenden selv afviste inputtet, returnerer kaldet `422 invalid_input` med dens meddelelse i stedet.

### `upstream_lost`

Modelbackendenden kender ikke længere anmodningen, så der kommer aldrig et resultat. Den afsluttes som `failed` med denne kode
(type `upstream_error`) og tilbagebetales. Kør den igen.

### `timeout`

Anmodningen kørte længere end dens grænse (15 minutter for billeder, 60 for video, 30 ellers) og blev stoppet. Den afsluttes som
`failed` med denne kode og tilbagebetales.

### `service_unavailable`

API'et er midlertidigt sat på pause, eller en afhængighed som filuploads er nede (503). Prøv igen senere.

### `internal_error`

Noget gik galt hos os (500). Prøv igen; kontakt support, hvis det fortsætter.

### `charge_failed`

Der kunne ikke opkræves betaling fra kontoen på grund af et internt problem (500). Anmodningen markeres som `failed`; intet blev
trukket. Prøv igen.

### `pricing_unavailable`

Modellens pris er ikke konfigureret, så den kan ikke beregnes eller køres lige nu (500).