# အမှားများ

Endpoint တိုင်းသည် တူညီသောနည်းလမ်းဖြင့် ပျက်ကွက်သည်။ HTTP status နှင့် JSON envelope တစ်ခု ပါဝင်သည်။

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

| Field | အဓိပ္ပာယ် |
|---|---|
| `type` | အမှား၏ အထွေထွေအမျိုးအစား။ ၎င်းမှ မည်သို့လုပ်ဆောင်ရမည်ကို ဆုံးဖြတ်ပါ။ |
| `code` | တိကျသောအကြောင်းရင်းဖြစ်ပြီး တည်ငြိမ်ကာ စက်ဖြင့်ဖတ်နိုင်သည်။ Code တိုင်းတွင် အောက်တွင် အပိုင်းတစ်ခုရှိပြီး `doc_url` က ၎င်းထံသို့ လင့်ခ်ချိတ်ထားသည်။ |
| `message` | လူဖတ်နိုင်သော ရှင်းလင်းချက်ဖြစ်ပြီး မှတ်တမ်းတင်ရန် သို့မဟုတ် ဆော့ဖ်ဝဲရေးသားသူထံ ပြသရန် ဘေးကင်းသည်။ |
| `param` | အမှားဖြစ်စေသော ထည့်သွင်းချက် ပါရာမီတာ သို့မဟုတ် header ရှိပါက ၎င်းကို ဖော်ပြသည်။ |
| `details` | ထည့်သွင်းချက်အမှားများအတွက် တွေ့ရှိသည့် ပြဿနာတိုင်း: `[{ "param", "message" }]`။ |
| `request_id` | သက်ဆိုင်သည့် တောင်းဆိုချက်ရှိပါက ၎င်းကို ဖော်ပြသည်။ |

အမှားပြန်ပေးသော ခေါ်ဆိုမှုအတွက် မည်သည့်အရာမျှ ကောက်ခံမည်မဟုတ်ပါ။ လက်ခံပြီးနောက် *ပျက်ကွက်* သည့် တောင်းဆိုချက်သည် status
`failed` ကို ဆက်လက်ထားရှိပြီး တောင်းဆိုချက်အရာဝတ္ထုတွင် `error: { "type", "code", "message" }` ပါဝင်ကာ ငွေပြန်အမ်းမှုကို အလိုအလျောက် ပြုလုပ်ပေးသည်။

## အမျိုးအစားများ

| အမျိုးအစား | HTTP status | လုပ်ဆောင်ရန် |
|---|---|---|
| `invalid_request` | 400, 413 သို့မဟုတ် 422 | တောင်းဆိုချက်ကို ပြင်ဆင်ပါ။ တူညီသော ခေါ်ဆိုမှုကို ထပ်မံကြိုးစားလည်း ထပ်မံပျက်ကွက်မည်။ |
| `authentication_error` | 401 | `Authorization: Bearer <key>` တွင် မှန်ကန်သော ကီးတစ်ခု ပေးပို့ပါ။ |
| `permission_error` | 403 | လိုအပ်သော scope ပါသည့် ကီးကို အသုံးပြုပါ။ |
| `not_found` | 404 | မော်ဒယ် id သို့မဟုတ် တောင်းဆိုချက် id ကို စစ်ဆေးပါ။ |
| `insufficient_credits` | 402 | API လက်ကျန်တွင် ငွေဖြည့်ပါ (`top_up_url` ကို အမှားထဲတွင် တွေ့ရမည်)။ |
| `budget_exceeded` | 402 | ကီး၏ ကိုယ်ပိုင် ဘတ်ဂျက် ကုန်ဆုံးသွားသည်။ နောက်ဆုံးလုပ်ဆောင်ရန်: ကီးပိုင်ရှင်အား တိုးမြှင့်ပေးရန် တောင်းဆိုပါ။ |
| `conflict` | 409 | အရင်းအမြစ်သည် ဤခေါ်ဆိုမှုကို ခွင့်ပြုသည့် အခြေအနေတွင် မရှိပါ။ |
| `rate_limited` | 429 | `Retry-After` စက္ကန့်များကို စောင့်ပြီးနောက် ထပ်မံကြိုးစားပါ။ |
| `upstream_error` | 502 | မော်ဒယ် backend ပျက်ကွက်သည်။ တူညီသော `Idempotency-Key` ဖြင့် ထပ်မံကြိုးစားနိုင်သည်။ ထပ်မံလုပ်ဆောင်မည်ဖြစ်ပြီး ငွေမကောက်ခံထားပါ။ |
| `service_unavailable` | 503 | API ကို ခေတ္တရပ်ထားခြင်း သို့မဟုတ် အားကိုးရသည့် ဝန်ဆောင်မှုတစ်ခု ပျက်နေခြင်း ဖြစ်သည်။ နောက်မှ ထပ်မံကြိုးစားပါ။ |
| `internal_error` | 500 | ကျွန်ုပ်တို့ဘက်မှ အမှားဖြစ်သည်။ ထပ်မံကြိုးစားပါ။ ဆက်ဖြစ်နေပါက အချိန်နှင့် `request_id` ဖြင့် support ကို ဆက်သွယ်ပါ။ |

## Code များ

### `invalid_request`

ပုံစံမမှန်သော တောင်းဆိုချက်အထွေထွေ (400)။

### `invalid_json`

Body သည် မှန်ကန်သော JSON မဟုတ်ပါ (400)။

### `invalid_body`

Body သည် မှန်ကန်သော JSON ဖြစ်သော်လည်း object မဟုတ်ပါ။ မော်ဒယ်ထည့်သွင်းချက်သည် JSON object ဖြစ်ရမည် (400)။

### `body_too_large`

Body သည် 16 MB ထက် ကြီးသည် (413)။ ဖိုင်ကြီးများကို upload လုပ်ပြီး ၎င်းတို့၏ URL ကို အစားထိုးပေးပို့ပါ ([Files](https://doitong.com/developers/docs/files) ကို ကြည့်ပါ)။

### `invalid_parameter`

Query ပါရာမီတာတွင် မှားယွင်းသောတန်ဖိုး ပါဝင်သည်။ ဥပမာ `limit` သည် 1 မှ 100 အတွင်း မရှိခြင်း၊ `wait` သည် နံပါတ်မဟုတ်ခြင်း၊ မသိသော
`status` သို့မဟုတ် `category` ဖြစ်ခြင်း၊ သို့မဟုတ် `permanent` / `temporary` မဟုတ်သော `storage` ဖြစ်ခြင်း (400)။ `param` က ၎င်းကို ဖော်ပြသည်။

### `invalid_category`

`GET /openapi.json?category=` သည် မရှိသော category တစ်ခုကို အမည်ပေးထားသည် (400)။ `GET https://api.doitong.com/v1/categories` က ၎င်းတို့ကို စာရင်းပြုစုသည်။

### `invalid_cursor`

စာရင်းခေါ်ဆိုမှု၏ `cursor` သည် ဤစာရင်းနှင့် မသက်ဆိုင်ပါ (400)။ Cursor မပါဘဲ အစမှ ပြန်စပါ။

### `invalid_idempotency_key`

`Idempotency-Key` header သည် ဗလာဖြစ်နေခြင်း သို့မဟုတ် စာလုံး 255 ထက် ပိုခြင်း ဖြစ်သည် (400)။

### `invalid_arguments`

MCP tool ခေါ်ဆိုမှုတွင် ပျောက်ဆုံးနေသော သို့မဟုတ် ပုံစံမမှန်သော argument ပါဝင်သည် (MCP သီးသန့်)။ `param` က argument ကို ဖော်ပြသည်။

### `invalid_input`

မော်ဒယ်ထည့်သွင်းချက်သည် validation မအောင်မြင်ပါ (422)။ မသိသော ပါရာမီတာ (message က အနီးစပ်ဆုံး မှန်ကန်သောအမည်ကို အကြံပြုသည်)၊
လိုအပ်သော ပါရာမီတာ ပျောက်ဆုံးခြင်း၊ အမျိုးအစားမှားခြင်း၊ ခွင့်ပြုထားသောစာရင်း သို့မဟုတ် အကွာအဝေးပြင်ပ တန်ဖိုးဖြစ်ခြင်း၊ သို့မဟုတ် canonical အမည်နှင့်
native အမည်နှစ်ခုလုံးကို မတူညီသောတန်ဖိုးများဖြင့် ပေးထားခြင်း ဖြစ်နိုင်သည်။ `param` သည် ပထမဆုံးအမှားရှိသော ပါရာမီတာဖြစ်ပြီး `details` က ၎င်းတို့အားလုံးကို စာရင်းပြုစုသည်။
မည်သည့်အရာမျှ ကောက်ခံမည်မဟုတ်ပါ။

### `unsupported_file`

ဖိုင်တွင် ကျွန်ုပ်တို့လက်မခံသော အမျိုးအစား ပါဝင်သည် (422)။ ဥပမာ မပံ့ပိုးသော extension ဖြင့် upload လုပ်ထားခြင်း သို့မဟုတ် extension နှင့် မကိုက်ညီသော `content_type` ဖြစ်ခြင်း။

### `invalid_webhook_url`

`webhook_url` သည် အများပြည်သူသုံး `https://` URL မဟုတ်ပါ (422)။ Private၊ local နှင့် ရိုးရိုး `http://` လိပ်စာများကို ငြင်းပယ်သည်။

### `missing_api_key`

Endpoint တွင် API ကီး လိုအပ်သော်လည်း မည်သည့်ကီးမျှ ပေးပို့ထားခြင်းမရှိပါ (401)။

### `invalid_api_key`

ကီးကို မသိခြင်း၊ ရုပ်သိမ်းထားခြင်း သို့မဟုတ် သက်တမ်းကုန်ဆုံးခြင်း ဖြစ်သည် (401)။

### `insufficient_scope`

ဤခေါ်ဆိုမှုလိုအပ်သော scope ကို ကီးတွင် မပါရှိပါ (403)။ ဥပမာ run အတွက် `models:run` သို့မဟုတ်
တောင်းဆိုချက်များနှင့် လက်ကျန်ကို ဖတ်ရန် `models:read` ဖြစ်သည်။ [Authentication](https://doitong.com/developers/docs/authentication#scopes) ကို ကြည့်ပါ။

### `account_disabled`

အကောင့်ကို ပိတ်ထားခြင်း သို့မဟုတ် ဆိုင်းငံ့ထားခြင်း ဖြစ်သည် (403)။ ၎င်း၏ကီးများ အလုပ်မလုပ်တော့ပါ။

### `not_found`

Path မရှိပါ (404)။

### `model_not_found`

ဤ id ဖြင့် အများပြည်သူသုံး မော်ဒယ်မရှိပါ (404)။ `GET https://api.doitong.com/v1/models` ဖြင့် မော်ဒယ်များကို စာရင်းပြုစုပါ။

### `request_not_found`

ဤ id ဖြင့် သင့်အကောင့်တွင် တောင်းဆိုချက်မရှိပါ (404)။ အခြားအကောင့်များ၏ တောင်းဆိုချက်များကို မည်သည့်အခါမျှ မြင်နိုင်မည်မဟုတ်ပါ။

### `insufficient_credits`

အကောင့်၏ **API လက်ကျန်** (API ခရက်ဒစ်၊ ၁,၀၀၀ API ခရက်ဒစ် = ၁ $ — Doitong အက်ပ်များ၏ ခရက်ဒစ်မဟုတ်ပါ) သည် ဤခေါ်ဆိုမှု၏ စျေးနှုန်းကို မလုံလောက်ပါ
(402)။ မည်သည့်အရာမျှ မကောက်ခံမီ response ကို ပေးပို့သည်။ အမှားတွင် `top_up_url` ပါဝင်သည်။ [https://doitong.com/developers/dashboard#balance](https://doitong.com/developers/dashboard#balance) တွင် ငွေဖြည့်ပြီး ထပ်မံကြိုးစားပါ။

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

ခေါ်ဆိုမှုသည် API ကီး၏ ကိုယ်ပိုင် API ခရက်ဒစ် ဘတ်ဂျက်ကို ကျော်လွန်မည် (402)။ ဘတ်ဂျက်ကို ကီးပိုင်ရှင်က သတ်မှတ်ထားသည်။ ၎င်းတို့က တိုးမြှင့်မပေးမချင်း ထပ်မံကြိုးစားခြင်းဖြင့် အဆင်ပြေမည်မဟုတ်ပါ။

### `conflict`

ခေါ်ဆိုမှုသည် အရင်းအမြစ်၏ လက်ရှိအခြေအနေနှင့် ဆန့်ကျင်နေသည် (409)။

### `idempotency_mismatch`

`Idempotency-Key` ကို မတူညီသော body ဖြင့် အသုံးပြုပြီးသား ဖြစ်သည် (409)။ လုပ်ဆောင်ချက်အသစ်အတွက် ကီးအသစ်ကို အသုံးပြုပါ။

### `idempotency_in_progress`

တူညီသော `Idempotency-Key` ဖြင့် တောင်းဆိုချက်တစ်ခုကို ယခုပင် ဖန်တီးနေသည် (409)။ ၎င်းကို ရရှိရန် ခဏအကြာတွင် ထပ်မံကြိုးစားပါ။

### `request_active`

တောင်းဆိုချက်သည် `queued` သို့မဟုတ် `running` ဖြစ်နေဆဲဖြစ်သောကြောင့် ဖျက်ရန် ဖိုင်များ မရှိသေးပါ (409)။ ပြီးဆုံးသည့်အခါ ဖျက်ပါ။

### `not_cancelable`

တောင်းဆိုချက်သည် `succeeded` သို့မဟုတ် `failed` ဖြစ်ပြီးသားဖြစ်၍ ပယ်ဖျက်၍မရပါ (409)။

### `rate_limited`

လက်ရှိ window အတွင်း ကီးက တောင်းဆိုချက်များ အလွန်များစွာ ပြုလုပ်ထားသည် (429)။ `X-RateLimit-*` နှင့် `Retry-After` headers များကို ကြည့်ပါ။

### `too_many_inflight`

အကောင့်တွင် `queued` သို့မဟုတ် `running` ဖြစ်နေသော တောင်းဆိုချက် 10 ခု ရှိပြီးသားဖြစ်သည် (429)။ ၎င်းတို့ထဲမှ တစ်ခု ပြီးဆုံးသည့်အခါ နောက်တစ်ခုကို စတင်ပါ။

### `upstream_error`

မော်ဒယ် backend က တောင်းဆိုချက်ကို ငြင်းပယ်ခြင်း သို့မဟုတ် ပျက်ကွက်ခြင်း ဖြစ်သည် (run တွင် 502 သို့မဟုတ် တောင်းဆိုချက်တွင် ဤ code ဖြင့် `failed`)။ API ခရက်ဒစ်များကို
ငွေပြန်အမ်းသည်။ Backend က ထည့်သွင်းချက်ကို ကိုယ်တိုင် ငြင်းပယ်ခဲ့ပါက ခေါ်ဆိုမှုသည် ၎င်း၏ message နှင့်အတူ `422 invalid_input` ကို ပြန်ပေးသည်။

### `upstream_lost`

မော်ဒယ် backend သည် တောင်းဆိုချက်ကို မသိတော့သဖြင့် ရလဒ် မည်သည့်အခါမျှ ရရှိမည်မဟုတ်ပါ။ ဤ code ဖြင့် `failed` အဖြစ်
(type `upstream_error`) အဆုံးသတ်ပြီး ငွေပြန်အမ်းသည်။ ထပ်မံလုပ်ဆောင်ပါ။

### `timeout`

တောင်းဆိုချက်သည် သတ်မှတ်ထားသော ကန့်သတ်ချိန်ထက် ပိုကြာသွားသောကြောင့် ရပ်တန့်ခဲ့သည် (ပုံများအတွက် 15 မိနစ်၊ ဗီဒီယိုအတွက် 60၊ အခြားအရာများအတွက် 30)။ ၎င်းသည်
ဤ code ဖြင့် `failed` အဖြစ် အဆုံးသတ်ပြီး ငွေပြန်အမ်းသည်။

### `service_unavailable`

API ကို ယာယီရပ်ထားခြင်း သို့မဟုတ် ဖိုင် upload များကဲ့သို့ အားကိုးရသည့် ဝန်ဆောင်မှု ပျက်နေခြင်း ဖြစ်သည် (503)။ နောက်မှ ထပ်မံကြိုးစားပါ။

### `internal_error`

ကျွန်ုပ်တို့ဘက်တွင် တစ်စုံတစ်ရာ ပျက်ကွက်သွားသည် (500)။ ထပ်မံကြိုးစားပါ။ ဆက်ဖြစ်နေပါက support ကို ဆက်သွယ်ပါ။

### `charge_failed`

အတွင်းပိုင်းပြဿနာကြောင့် အကောင့်မှ ငွေမကောက်ခံနိုင်ပါ (500)။ တောင်းဆိုချက်ကို `failed` အဖြစ် မှတ်သားထားပြီး မည်သည့်ငွေမျှ
မယူထားပါ။ ထပ်မံကြိုးစားပါ။

### `pricing_unavailable`

မော်ဒယ်၏ စျေးနှုန်းကို သတ်မှတ်ထားခြင်းမရှိသဖြင့် ယခုအချိန်တွင် စျေးနှုန်းဖော်ပြခြင်း သို့မဟုတ် လုပ်ဆောင်ခြင်း မပြုနိုင်ပါ (500)။