# Fouten

Elk endpoint mislukt op dezelfde manier: een HTTP-status en één JSON-envelop.

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

| Veld | Betekenis |
|---|---|
| `type` | Algemene klasse van de fout. Bepaal hiermee wat je moet doen. |
| `code` | Exacte reden, stabiel en machineleesbaar. Elke code heeft hieronder een sectie; `doc_url` verwijst ernaar. |
| `message` | Voor mensen leesbare uitleg, veilig om te loggen of aan een ontwikkelaar te tonen. |
| `param` | De invoerparameter of header die de fout veroorzaakt, indien aanwezig. |
| `details` | Voor invoerfouten elk gevonden probleem: `[{ "param", "message" }]`. |
| `request_id` | De request waarop dit betrekking heeft, indien aanwezig. |

Voor een aanroep die een fout retourneert, worden geen kosten in rekening gebracht. Een request die *nadat* deze is geaccepteerd mislukt, behoudt de status
`failed`, bevat `error: { "type", "code", "message" }` op het request-object en wordt automatisch terugbetaald.

## Typen

| Type | HTTP-status | Wat te doen |
|---|---|---|
| `invalid_request` | 400, 413 of 422 | Corrigeer de request. Dezelfde aanroep opnieuw proberen mislukt opnieuw. |
| `authentication_error` | 401 | Stuur een geldige sleutel in `Authorization: Bearer <key>`. |
| `permission_error` | 403 | Gebruik een sleutel met de vereiste scope. |
| `not_found` | 404 | Controleer de model-id of request-id. |
| `insufficient_credits` | 402 | Waardeer het API-saldo op (`top_up_url` in de fout). |
| `budget_exceeded` | 402 | Het eigen budget van de sleutel is opgebruikt. Definitief: vraag de eigenaar van de sleutel om het te verhogen. |
| `conflict` | 409 | De resource bevindt zich niet in een toestand waarin deze aanroep is toegestaan. |
| `rate_limited` | 429 | Wacht `Retry-After` seconden en probeer het opnieuw. |
| `upstream_error` | 502 | De modelbackend is mislukt. Opnieuw proberen met dezelfde `Idempotency-Key` is veilig: de aanroep wordt opnieuw uitgevoerd; er zijn geen kosten in rekening gebracht. |
| `service_unavailable` | 503 | De API is gepauzeerd of een afhankelijkheid is uitgevallen. Probeer het later opnieuw. |
| `internal_error` | 500 | Onze fout. Probeer het opnieuw; neem bij aanhoudende problemen contact op met support en vermeld het tijdstip en `request_id`. |

## Codes

### `invalid_request`

Algemene onjuist gevormde request (400).

### `invalid_json`

De body is geen geldige JSON (400).

### `invalid_body`

De body is geldige JSON maar geen object; modelinvoer moet een JSON-object zijn (400).

### `body_too_large`

De body is groter dan 16 MB (413). Upload grote bestanden en geef in plaats daarvan hun URL door (zie [Bestanden](https://doitong.com/developers/docs/files)).

### `invalid_parameter`

Een queryparameter heeft een onjuiste waarde, bijvoorbeeld `limit` buiten 1 tot 100, `wait` is geen getal, een onbekende
`status` of `category`, of `storage` is anders dan `permanent` / `temporary` (400). `param` vermeldt welke.

### `invalid_category`

`GET /openapi.json?category=` vermeldt een categorie die niet bestaat (400). `GET https://api.doitong.com/v1/categories` geeft de lijst.

### `invalid_cursor`

De `cursor` van een lijstaanroep hoort niet bij deze lijst (400). Begin opnieuw zonder cursor.

### `invalid_idempotency_key`

De header `Idempotency-Key` is leeg of langer dan 255 tekens (400).

### `invalid_arguments`

Een MCP-toolaanroep heeft een ontbrekend of onjuist gevormd argument (alleen MCP). `param` vermeldt het argument.

### `invalid_input`

De modelinvoer doorstaat de validatie niet (422): een onbekende parameter (het bericht stelt de dichtstbijzijnde geldige naam voor),
een ontbrekende vereiste parameter, een onjuist type, een waarde buiten de toegestane lijst of het bereik, of zowel de canonieke als de
native naam met verschillende waarden. `param` is de eerste problematische parameter en `details` bevat ze allemaal.
Er worden geen kosten in rekening gebracht.

### `unsupported_file`

Een bestand heeft een type dat we niet accepteren (422), bijvoorbeeld een upload met een niet-ondersteunde extensie, of een `content_type`
die niet overeenkomt met de extensie.

### `invalid_webhook_url`

`webhook_url` is geen openbare `https://`-URL (422). Privé-, lokale en gewone `http://`-adressen worden geweigerd.

### `missing_api_key`

Het endpoint vereist een API-sleutel en er is geen sleutel verzonden (401).

### `invalid_api_key`

De sleutel is onbekend, ingetrokken of verlopen (401).

### `insufficient_scope`

De sleutel heeft niet de scope die deze aanroep nodig heeft (403), bijvoorbeeld `models:run` voor een run of `models:read` om
requests en het saldo te lezen. Zie [Authenticatie](https://doitong.com/developers/docs/authentication#scopes).

### `account_disabled`

Het account is gesloten of opgeschort (403). De sleutels ervan werken niet meer.

### `not_found`

Het pad bestaat niet (404).

### `model_not_found`

Geen openbaar model heeft deze id (404). Geef modellen weer met `GET https://api.doitong.com/v1/models`.

### `request_not_found`

Er bestaat geen request met deze id in je account (404). Requests van andere accounts zijn nooit zichtbaar.

### `insufficient_credits`

Het **API-saldo** van het account (API-credits, 1.000 API-tegoed = $ 1 — niet de credits van de Doitong-apps) dekt de
prijs van deze aanroep niet (402). Het antwoord wordt verzonden voordat er kosten in rekening worden gebracht. De fout bevat `top_up_url`; voeg geld toe via
[https://doitong.com/developers/dashboard#balance](https://doitong.com/developers/dashboard#balance) en probeer het opnieuw.

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

De aanroep zou het eigen budget van de API-sleutel in API-credits overschrijden (402). Het budget wordt ingesteld door de eigenaar van de sleutel; opnieuw proberen helpt niet
totdat diegene het verhoogt.

### `conflict`

De aanroep is in conflict met de huidige toestand van de resource (409).

### `idempotency_mismatch`

De `Idempotency-Key` is al gebruikt met een andere body (409). Gebruik een nieuwe sleutel voor een nieuwe bewerking.

### `idempotency_in_progress`

Er wordt nu een request met dezelfde `Idempotency-Key` aangemaakt (409). Probeer over een moment opnieuw om deze op te halen.

### `request_active`

De request staat nog op `queued` of `running`, dus er zijn nog geen bestanden om te verwijderen (409). Verwijder ze zodra de request is voltooid.

### `not_cancelable`

De request is al `succeeded` of `failed` en kan niet worden geannuleerd (409).

### `rate_limited`

De sleutel heeft in het huidige venster te veel requests gedaan (429). Zie de headers `X-RateLimit-*` en `Retry-After`.

### `too_many_inflight`

Het account heeft al 10 requests op `queued` of `running` (429). Start de volgende zodra een daarvan is voltooid.

### `upstream_error`

De modelbackend heeft de request geweigerd of kon deze niet uitvoeren (502 bij run, of `failed` met deze code op het request-object). De API-credits worden
terugbetaald. Als de backend de invoer zelf heeft afgewezen, retourneert de aanroep in plaats daarvan `422 invalid_input` met het bijbehorende bericht.

### `upstream_lost`

De modelbackend kent de request niet meer, dus er zal nooit een resultaat aankomen. De request eindigt als `failed` met deze code
(type `upstream_error`) en wordt terugbetaald. Voer de request opnieuw uit.

### `timeout`

De request liep langer dan de limiet (15 minuten voor afbeeldingen, 60 voor video, 30 anders) en is gestopt. De request eindigt als
`failed` met deze code en wordt terugbetaald.

### `service_unavailable`

De API is tijdelijk gepauzeerd of een afhankelijkheid, zoals bestanduploads, is uitgevallen (503). Probeer het later opnieuw.

### `internal_error`

Er is iets misgegaan aan onze kant (500). Probeer het opnieuw; neem bij aanhoudende problemen contact op met support.

### `charge_failed`

Het account kon door een intern probleem niet worden belast (500). De request krijgt de status `failed`; er is niets afgeschreven. Probeer het opnieuw.

### `pricing_unavailable`

De prijs van het model is niet geconfigureerd, dus het kan momenteel niet worden geprijsd of uitgevoerd (500).