# Earráidí

Teipeann ar gach críochphointe ar an mbealach céanna: stádas HTTP agus clúdachán JSON amháin.

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

| Réimse | Brí |
|---|---|
| `type` | Aicme ghinearálta na hearráide. Socraigh cad atá le déanamh as seo. |
| `code` | An chúis bheacht, chobhsaí agus inléite ag meaisín. Tá rannán thíos ag gach cód; nascann `doc_url` leis. |
| `message` | Míniú inléite ag duine, sábháilte le logáil nó le taispeáint d’fhorbróir. |
| `param` | An paraiméadar ionchuir nó an ceanntásc atá lochtach, nuair atá ceann ann. |
| `details` | Maidir le hearráidí ionchuir, gach fadhb a aimsíodh: `[{ "param", "message" }]`. |
| `request_id` | An t-iarratas lena mbaineann sé, nuair atá ceann ann. |

Ní ghearrtar aon táille ar ghlao a thugann earráid ar ais. Coinníonn iarratas a theipeann *tar éis* dó a bheith glactha an stádas
`failed`, iompraíonn sé `error: { "type", "code", "message" }` ar oibiacht an iarratais, agus faigheann sé aisíocaíocht go huathoibríoch.

## Cineálacha

| Cineál | Stádas HTTP | Cad atá le déanamh |
|---|---|---|
| `invalid_request` | 400, 413 nó 422 | Ceartaigh an t-iarratas. Teipfidh arís ar an nglao céanna a thriail. |
| `authentication_error` | 401 | Seol eochair bhailí in `Authorization: Bearer <key>`. |
| `permission_error` | 403 | Úsáid eochair a bhfuil an scóip riachtanach aici. |
| `not_found` | 404 | Seiceáil aitheantas na samhla nó aitheantas an iarratais. |
| `insufficient_credits` | 402 | Déan breisiú ar iarmhéid API (`top_up_url` san earráid). |
| `budget_exceeded` | 402 | Tá buiséad na heochrach ídithe. Deiridh: iarr ar úinéir na heochrach é a ardú. |
| `conflict` | 409 | Níl an acmhainn i staid a cheadaíonn an glao seo. |
| `rate_limited` | 429 | Fan `Retry-After` soicind, ansin bain triail eile as. |
| `upstream_error` | 502 | Theip ar inneall na samhla. Tá sé sábháilte triail eile a bhaint as leis an `Idempotency-Key` céanna: rithfidh sé arís; níor gearradh táille ort. |
| `service_unavailable` | 503 | Tá an API ar sos nó tá spleáchas as feidhm. Bain triail eile as níos déanaí. |
| `internal_error` | 500 | Fabht againne. Bain triail eile as; má leanann sé ar aghaidh, déan teagmháil leis an tacaíocht leis an am agus `request_id`. |

## Cóid

### `invalid_request`

Iarratas ginearálta míchumtha (400).

### `invalid_json`

Níl an corp ina JSON bailí (400).

### `invalid_body`

Is JSON bailí é an corp ach ní oibiacht é; caithfidh ionchur na samhla a bheith ina oibiacht JSON (400).

### `body_too_large`

Tá an corp níos mó ná 16 MB (413). Uaslódáil comhaid mhóra agus cuir a URL ar aghaidh ina n-áit (féach [Comhaid](https://doitong.com/developers/docs/files)).

### `invalid_parameter`

Tá luach mícheart ag paraiméadar fiosraithe, mar shampla `limit` lasmuigh de 1 go 100, `wait` nach uimhir é, `status` nó `category` anaithnid,
`storage` seachas `permanent` / `temporary` (400). Ainmníonn `param` é.

### `invalid_category`

Ainmníonn `GET /openapi.json?category=` catagóir nach bhfuil ann (400). Liostaíonn `GET https://api.doitong.com/v1/categories` iad.

### `invalid_cursor`

Ní bhaineann `cursor` glao liosta leis an liosta seo (400). Tosaigh arís gan cúrsóir.

### `invalid_idempotency_key`

Tá ceanntásc `Idempotency-Key` folamh nó níos faide ná 255 carachtar (400).

### `invalid_arguments`

Tá argóint in easnamh nó míchumtha i nglao uirlise MCP (MCP amháin). Ainmníonn `param` an argóint.

### `invalid_input`

Ní éiríonn le hionchur na samhla an bailíochtú (422): paraiméadar anaithnid (molann an teachtaireacht an t-ainm bailí is gaire),
paraiméadar riachtanach in easnamh, cineál mícheart, luach lasmuigh den liosta nó den raon ceadaithe, nó tugadh an t-ainm canónach agus an t-ainm dúchasach araon le luachanna éagsúla. Is é `param` an chéad pharaiméadar ciontach agus liostaíonn `details` iad go léir.
Ní ghearrtar aon táille.

### `unsupported_file`

Tá cineál comhaid ann nach nglacaimid leis (422), mar shampla uaslódáil le hiarmhír nach dtacaítear leis, nó `content_type`
nach gcomhfhreagraíonn don iarmhír.

### `invalid_webhook_url`

Ní URL poiblí `https://` é `webhook_url` (422). Diúltaítear do sheoltaí príobháideacha, logánta agus simplí `http://`.

### `missing_api_key`

Teastaíonn eochair API ón gcríochphointe agus níor seoladh ceann ar bith (401).

### `invalid_api_key`

Tá an eochair anaithnid, cúlghairthe nó imithe in éag (401).

### `insufficient_scope`

Níl an scóip atá riachtanach don ghlao seo ag an eochair (403), mar shampla `models:run` le haghaidh rith, nó `models:read` chun
 iarratais agus an t-iarmhéid a léamh. Féach [Fíordheimhniú](https://doitong.com/developers/docs/authentication#scopes).

### `account_disabled`

Tá an cuntas dúnta nó curtha ar fionraí (403). Ní oibríonn a eochracha a thuilleadh.

### `not_found`

Níl an cosán ann (404).

### `model_not_found`

Níl aon samhail phoiblí leis an aitheantas seo (404). Liostaigh samhlacha le `GET https://api.doitong.com/v1/models`.

### `request_not_found`

Níl aon iarratas leis an aitheantas seo i do chuntas (404). Ní bhíonn iarratais ó chuntais eile le feiceáil riamh.

### `insufficient_credits`

Ní chlúdaíonn **iarmhéid API** an chuntais (creidmheasanna API, 1,000 gcreidmheas API = $1 — ní creidmheasanna aipeanna Doitong) praghas an ghlao seo (402). Seoltar an freagra sula ngearrtar aon rud. Tá `top_up_url` san earráid; cuir airgead leis ag [https://doitong.com/developers/dashboard#balance](https://doitong.com/developers/dashboard#balance) agus bain triail eile as.

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

Sháródh an glao buiséad na heochrach API féin i gcreidmheasanna API (402). Socraíonn úinéir na heochrach an buiséad; ní chabhraíonn triail eile go n-ardaítear é.

### `conflict`

Tagann an glao salach ar staid reatha na hacmhainne (409).

### `idempotency_mismatch`

Úsáideadh an `Idempotency-Key` cheana le corp eile (409). Úsáid eochair nua le haghaidh oibríochta nua.

### `idempotency_in_progress`

Tá iarratas leis an `Idempotency-Key` céanna á chruthú anois (409). Bain triail eile as ar ball chun é a fháil.

### `request_active`

Tá an t-iarratas fós `queued` nó `running`, mar sin níl aon chomhaid aige le scriosadh fós (409). Scrios iad nuair a bheidh sé críochnaithe.

### `not_cancelable`

Tá an t-iarratas `succeeded` nó `failed` cheana agus ní féidir é a chealú (409).

### `rate_limited`

Rinne an eochair an iomarca iarratas sa bhfuinneog reatha (429). Féach ar na ceanntásca `X-RateLimit-*` agus `Retry-After`.

### `too_many_inflight`

Tá 10 n-iarratas `queued` nó `running` ag an gcuntas cheana (429). Tosaigh an chéad cheann eile nuair a chríochnaíonn ceann acu.

### `upstream_error`

Dhiúltaigh inneall na samhla don iarratas nó theip air (502 ar rith, nó `failed` leis an gcód seo ar an iarratas). Déantar aisíocaíocht ar na creidmheasanna API. Má dhiúltaigh an t-inneall don ionchur féin, tugann an glao `422 invalid_input` ar ais lena theachtaireacht ina áit.

### `upstream_lost`

Ní aithníonn inneall na samhla an t-iarratas a thuilleadh, mar sin ní thiocfaidh toradh riamh. Críochnaíonn sé mar `failed` leis an gcód seo (cineál `upstream_error`) agus faigheann sé aisíocaíocht. Rith arís é.

### `timeout`

Rith an t-iarratas níos faide ná a theorainn (15 nóiméad le haghaidh íomhánna, 60 le haghaidh físeáin, 30 ar shlí eile) agus cuireadh stop leis. Críochnaíonn sé mar `failed` leis an gcód seo agus faigheann sé aisíocaíocht.

### `service_unavailable`

Tá an API ar sos go sealadach, nó tá spleáchas ar nós uaslódálacha comhad as feidhm (503). Bain triail eile as níos déanaí.

### `internal_error`

Tharla fadhb ar ár dtaobh (500). Bain triail eile as; má leanann sé ar aghaidh, déan teagmháil leis an tacaíocht.

### `charge_failed`

Níorbh fhéidir táille a ghearradh ar an gcuntas mar gheall ar fhadhb inmheánach (500). Marcáiltear an t-iarratas mar `failed`; níor tógadh aon rud. Bain triail eile as.

### `pricing_unavailable`

Níl praghas na samhla cumraithe, mar sin ní féidir é a lua ná a rith faoi láthair (500).