# Gwallau

Mae pob diweddbwynt yn methu yn yr un ffordd: statws HTTP ac amlen JSON unigol.

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

| Maes | Ystyr |
|---|---|
| `type` | Dosbarth eang y gwall. Penderfynwch beth i'w wneud ar sail hwn. |
| `code` | Yr union reswm, sefydlog ac yn ddarllenadwy gan beiriant. Mae gan bob cod adran isod; mae `doc_url` yn cysylltu â hi. |
| `message` | Esboniad darllenadwy i bobl, yn ddiogel i'w gofnodi neu ei ddangos i ddatblygwr. |
| `param` | Y paramedr mewnbwn neu'r pennawd sydd ar fai, pan fo un. |
| `details` | Ar gyfer gwallau mewnbwn, pob problem a ganfuwyd: `[{ "param", "message" }]`. |
| `request_id` | Y cais y mae'n ymwneud ag ef, pan fo un yn bodoli. |

Ni chodir tâl am alwad sy'n dychwelyd gwall. Mae cais sy'n methu *ar ôl* cael ei dderbyn yn cadw'r statws
`failed`, yn cynnwys `error: { "type", "code", "message" }` ar wrthrych y cais, ac yn cael ad-daliad yn awtomatig.

## Mathau

| Math | Statws HTTP | Beth i'w wneud |
|---|---|---|
| `invalid_request` | 400, 413 neu 422 | Cywirwch y cais. Bydd rhoi cynnig arall ar yr un alwad yn methu eto. |
| `authentication_error` | 401 | Anfonwch allwedd ddilys yn `Authorization: Bearer <key>`. |
| `permission_error` | 403 | Defnyddiwch allwedd â'r cwmpas angenrheidiol. |
| `not_found` | 404 | Gwiriwch ID y model neu ID y cais. |
| `insufficient_credits` | 402 | Gwnewch ychwanegiad i falans yr API (`top_up_url` yn y gwall). |
| `budget_exceeded` | 402 | Mae cyllideb yr allwedd ei hun wedi'i defnyddio. Terfynol: gofynnwch i berchennog yr allwedd ei chodi. |
| `conflict` | 409 | Nid yw'r adnodd mewn cyflwr sy'n caniatáu'r alwad hon. |
| `rate_limited` | 429 | Arhoswch `Retry-After` eiliad, yna rhowch gynnig arall arni. |
| `upstream_error` | 502 | Methodd ôl-wyneb y model. Mae'n ddiogel rhoi cynnig arall arni gyda'r un `Idempotency-Key`: bydd yn rhedeg eto; ni chodwyd tâl arnoch. |
| `service_unavailable` | 503 | Mae'r API wedi'i oedi neu mae dibyniaeth i lawr. Rhowch gynnig arall yn nes ymlaen. |
| `internal_error` | 500 | Ein nam ni. Rhowch gynnig arall; os bydd yn parhau, cysylltwch â'r cymorth gan roi'r amser ac `request_id`. |

## Codau

### `invalid_request`

Cais generig wedi'i gamffurfio (400).

### `invalid_json`

Nid yw'r corff yn JSON dilys (400).

### `invalid_body`

Mae'r corff yn JSON dilys ond nid yw'n wrthrych; rhaid i fewnbwn y model fod yn wrthrych JSON (400).

### `body_too_large`

Mae'r corff yn fwy na 16 MB (413). Llwythwch ffeiliau mawr i fyny a phasiwch eu URL yn lle hynny (gweler [Ffeiliau](https://doitong.com/developers/docs/files)).

### `invalid_parameter`

Mae gan baramedr ymholiad werth anghywir, er enghraifft `limit` y tu allan i 1 i 100, `wait` nad yw'n rhif, `status` neu `category` anhysbys, neu `storage` heblaw `permanent` / `temporary` (400). Mae `param` yn ei enwi.

### `invalid_category`

Mae `GET /openapi.json?category=` yn enwi categori nad yw'n bodoli (400). Mae `GET https://api.doitong.ru/v1/categories` yn eu rhestru.

### `invalid_cursor`

Nid yw `cursor` galwad rhestr yn perthyn i'r rhestr hon (400). Dechreuwch eto heb gyrchwr.

### `invalid_idempotency_key`

Mae pennawd `Idempotency-Key` yn wag neu'n hwy na 255 nod (400).

### `invalid_arguments`

Mae galwad offeryn MCP yn cynnwys arg neu sydd wedi'i gamffurfio (MCP yn unig). Mae `param` yn enwi'r arg.

### `invalid_input`

Nid yw mewnbwn y model yn pasio dilysiad (422): paramedr anhysbys (mae'r neges yn awgrymu'r enw dilys agosaf), paramedr gofynnol ar goll, math anghywir, gwerth y tu allan i'r rhestr neu'r amrediad a ganiateir, neu'r enw canonaidd a'r enw brodorol ill dau wedi'u rhoi â gwerthoedd gwahanol. `param` yw'r paramedr tramgwyddus cyntaf ac mae `details` yn rhestru pob un. Ni chodir tâl.

### `unsupported_file`

Mae gan ffeil fath nad ydym yn ei dderbyn (422), er enghraifft uwchlwythiad ag estyniad heb ei gefnogi, neu `content_type` nad yw'n cyfateb i'r estyniad.

### `invalid_webhook_url`

Nid yw `webhook_url` yn URL cyhoeddus `https://` (422). Gwrthodir cyfeiriadau preifat, lleol a `http://` plaen.

### `missing_api_key`

Mae angen allwedd API ar y diweddbwynt ac ni anfonwyd un (401).

### `invalid_api_key`

Mae'r allwedd yn anhysbys, wedi'i dirymu neu wedi dod i ben (401).

### `insufficient_scope`

Nid oes gan yr allwedd y cwmpas sydd ei angen ar yr alwad hon (403), er enghraifft `models:run` ar gyfer rhediad, neu `models:read` i ddarllen ceisiadau a'r balans. Gweler [Dilysu](https://doitong.com/developers/docs/authentication#scopes).

### `account_disabled`

Mae'r cyfrif wedi'i gau neu ei atal (403). Nid yw ei allweddi'n gweithio mwyach.

### `not_found`

Nid yw'r llwybr yn bodoli (404).

### `model_not_found`

Nid oes gan unrhyw fodel cyhoeddus yr ID hwn (404). Rhestrwch y modelau gyda `GET https://api.doitong.ru/v1/models`.

### `request_not_found`

Nid oes cais â'r ID hwn yn bodoli yn eich cyfrif (404). Nid yw ceisiadau cyfrifon eraill byth yn weladwy.

### `insufficient_credits`

Nid yw **balans API** y cyfrif (credydau API, 1,000 o gredydau API = $1 — nid credydau apiau Doitong) yn ddigon i dalu am bris yr alwad hon (402). Anfonir yr ymateb cyn codi unrhyw dâl. Mae'r gwall yn cynnwys `top_up_url`; ychwanegwch arian yn [https://doitong.ru/developers/dashboard#balance](https://doitong.ru/developers/dashboard#balance) a rhowch gynnig arall.

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

Byddai'r alwad yn mynd dros gyllideb yr allwedd API ei hun mewn credydau API (402). Perchennog yr allwedd sy'n gosod y gyllideb; nid yw rhoi cynnig arall yn helpu nes iddo ei chodi.

### `conflict`

Mae'r alwad yn gwrthdaro â chyflwr presennol yr adnodd (409).

### `idempotency_mismatch`

Defnyddiwyd `Idempotency-Key` eisoes gyda chorff gwahanol (409). Defnyddiwch allwedd newydd ar gyfer gweithrediad newydd.

### `idempotency_in_progress`

Mae cais â'r un `Idempotency-Key` yn cael ei greu ar hyn o bryd (409). Rhowch gynnig arall mewn eiliad i'w gael.

### `request_active`

Mae'r cais yn dal yn `queued` neu `running`, felly nid oes ganddo ffeiliau i'w dileu eto (409). Dilëwch nhw ar ôl iddo orffen.

### `not_cancelable`

Mae'r cais eisoes yn `succeeded` neu `failed` ac ni ellir ei ganslo (409).

### `rate_limited`

Gwnaeth yr allwedd ormod o geisiadau yn y cyfnod presennol (429). Gweler y penawdau `X-RateLimit-*` a `Retry-After`.

### `too_many_inflight`

Mae gan y cyfrif 10 cais `queued` neu `running` eisoes (429). Dechreuwch yr un nesaf pan fydd un ohonynt yn gorffen.

### `upstream_error`

Gwrthododd neu methodd ôl-wyneb y model y cais (502 ar rediad, neu `failed` gyda'r cod hwn ar y cais). Rhoddir ad-daliad o'r credydau API. Os gwrthododd yr ôl-wyneb y mewnbwn ei hun, mae'r alwad yn dychwelyd `422 invalid_input` gyda'i neges yn lle hynny.

### `upstream_lost`

Nid yw ôl-wyneb y model yn adnabod y cais mwyach, felly ni fydd canlyniad byth yn cyrraedd. Mae'n gorffen fel `failed` gyda'r cod hwn (math `upstream_error`) ac yn cael ad-daliad. Rhedwch ef eto.

### `timeout`

Rhedodd y cais yn hirach na'i derfyn (15 munud ar gyfer delweddau, 60 ar gyfer fideo, 30 fel arall) a chafodd ei atal. Mae'n gorffen fel `failed` gyda'r cod hwn ac yn cael ad-daliad.

### `service_unavailable`

Mae'r API wedi'i oedi dros dro, neu mae dibyniaeth fel uwchlwythiadau ffeiliau i lawr (503). Rhowch gynnig arall yn nes ymlaen.

### `internal_error`

Aeth rhywbeth o'i le ar ein hochr ni (500). Rhowch gynnig arall; os bydd yn parhau, cysylltwch â'r cymorth.

### `charge_failed`

Ni ellid codi tâl ar y cyfrif oherwydd problem fewnol (500). Nodir y cais fel `failed`; ni chymerwyd dim. Rhowch gynnig arall.

### `pricing_unavailable`

Nid yw pris y model wedi'i ffurfweddu, felly ni ellir ei ddyfynnu na'i redeg ar hyn o bryd (500).