# ข้อผิดพลาด

ทุกเอนด์พอยต์ล้มเหลวในลักษณะเดียวกัน: สถานะ HTTP และซอง JSON หนึ่งรายการ

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

| ฟิลด์ | ความหมาย |
|---|---|
| `type` | คลาสกว้าง ๆ ของข้อผิดพลาด ใช้ข้อมูลนี้ตัดสินใจว่าควรทำอย่างไร |
| `code` | สาเหตุที่แน่นอน คงที่และอ่านได้โดยเครื่อง ทุกโค้ดมีหัวข้อด้านล่าง และ `doc_url` จะลิงก์ไปยังหัวข้อนั้น |
| `message` | คำอธิบายที่มนุษย์อ่านได้ ปลอดภัยสำหรับบันทึกหรือนำไปแสดงให้นักพัฒนาดู |
| `param` | พารามิเตอร์อินพุตหรือเฮดเดอร์ที่เป็นสาเหตุ หากมี |
| `details` | สำหรับข้อผิดพลาดของอินพุต ปัญหาทั้งหมดที่พบ: `[{ "param", "message" }]` |
| `request_id` | คำขอที่เกี่ยวข้อง หากมี |

จะไม่มีการเรียกเก็บเงินสำหรับการเรียกที่ส่งคืนข้อผิดพลาด คำขอที่ล้มเหลว *หลังจาก* ได้รับการยอมรับแล้วจะคงสถานะเป็น
`failed` มี `error: { "type", "code", "message" }` อยู่ในออบเจ็กต์คำขอ และจะได้รับการคืนเงินโดยอัตโนมัติ

## ประเภท

| ประเภท | สถานะ HTTP | สิ่งที่ต้องทำ |
|---|---|---|
| `invalid_request` | 400, 413 หรือ 422 | แก้ไขคำขอ การลองเรียกเดิมซ้ำจะล้มเหลวอีกครั้ง |
| `authentication_error` | 401 | ส่งคีย์ที่ถูกต้องใน `Authorization: Bearer <key>` |
| `permission_error` | 403 | ใช้คีย์ที่มีขอบเขตสิทธิ์ที่จำเป็น |
| `not_found` | 404 | ตรวจสอบรหัสโมเดลหรือรหัสคำขอ |
| `insufficient_credits` | 402 | เติมเงินในยอดคงเหลือ API (`top_up_url` ในข้อผิดพลาด) |
| `budget_exceeded` | 402 | ใช้งบประมาณของคีย์จนหมดแล้ว สุดท้ายให้ขอเจ้าของคีย์เพิ่มงบประมาณ |
| `conflict` | 409 | รีซอร์สอยู่ในสถานะที่ไม่อนุญาตให้เรียกนี้ |
| `rate_limited` | 429 | รอ `Retry-After` วินาที แล้วลองใหม่ |
| `upstream_error` | 502 | แบ็กเอนด์ของโมเดลล้มเหลว สามารถลองใหม่ด้วย `Idempotency-Key` เดิมได้ ระบบจะทำงานอีกครั้ง และจะไม่มีการเรียกเก็บเงิน |
| `service_unavailable` | 503 | API หยุดชั่วคราวหรือการพึ่งพาบริการบางอย่างไม่พร้อมใช้งาน ลองใหม่ภายหลัง |
| `internal_error` | 500 | เป็นข้อบกพร่องของเรา ลองใหม่ หากยังเกิดขึ้น โปรดติดต่อฝ่ายสนับสนุนพร้อมเวลาและ `request_id` |

## โค้ด

### `invalid_request`

คำขอมีรูปแบบไม่ถูกต้องทั่วไป (400)

### `invalid_json`

บอดีไม่ใช่ JSON ที่ถูกต้อง (400)

### `invalid_body`

บอดีเป็น JSON ที่ถูกต้องแต่ไม่ใช่ออบเจ็กต์ อินพุตโมเดลต้องเป็นออบเจ็กต์ JSON (400)

### `body_too_large`

บอดีมีขนาดใหญ่กว่า 16 MB (413) ให้อัปโหลดไฟล์ขนาดใหญ่และส่ง URL แทน (ดู [ไฟล์](https://doitong.com/developers/docs/files))

### `invalid_parameter`

พารามิเตอร์คิวรีมีค่าไม่ถูกต้อง เช่น `limit` อยู่นอกช่วง 1 ถึง 100, `wait` ไม่ใช่ตัวเลข, มี `status` หรือ `category` ที่ไม่รู้จัก หรือ `storage` ไม่ใช่ `permanent` / `temporary` (400) `param` จะระบุชื่อพารามิเตอร์นั้น

### `invalid_category`

`GET /openapi.json?category=` ระบุหมวดหมู่ที่ไม่มีอยู่ (400) `GET https://api.doitong.com/v1/categories` จะแสดงรายการหมวดหมู่

### `invalid_cursor`

`cursor` ของการเรียกรายการไม่ใช่ของรายการนี้ (400) ให้เริ่มใหม่โดยไม่ใช้เคอร์เซอร์

### `invalid_idempotency_key`

เฮดเดอร์ `Idempotency-Key` ว่างเปล่าหรือยาวเกิน 255 อักขระ (400)

### `invalid_arguments`

การเรียกเครื่องมือ MCP มีอาร์กิวเมนต์ที่หายไปหรือมีรูปแบบไม่ถูกต้อง (MCP เท่านั้น) `param` จะระบุชื่ออาร์กิวเมนต์

### `invalid_input`

อินพุตโมเดลไม่ผ่านการตรวจสอบ (422): พารามิเตอร์ที่ไม่รู้จัก (ข้อความจะแนะนำชื่อที่ถูกต้องซึ่งใกล้เคียงที่สุด), พารามิเตอร์ที่จำเป็นหายไป, ชนิดไม่ถูกต้อง, ค่าอยู่นอกช่วงหรือรายการที่อนุญาต หรือระบุทั้งชื่อมาตรฐานและชื่อเนทีฟด้วยค่าที่ต่างกัน `param` คือพารามิเตอร์แรกที่มีปัญหา และ `details` จะแสดงรายการทั้งหมด
จะไม่มีการเรียกเก็บเงิน

### `unsupported_file`

ไฟล์มีชนิดที่เราไม่ยอมรับ (422) เช่น การอัปโหลดที่มีส่วนขยายที่ไม่รองรับ หรือ `content_type` ไม่ตรงกับส่วนขยาย

### `invalid_webhook_url`

`webhook_url` ไม่ใช่ URL สาธารณะ `https://` (422) ระบบปฏิเสธที่อยู่ส่วนตัว ที่อยู่ภายในเครื่อง และที่อยู่ `http://` ธรรมดา

### `missing_api_key`

เอนด์พอยต์ต้องใช้คีย์ API แต่ไม่มีการส่งคีย์มา (401)

### `invalid_api_key`

ไม่รู้จักคีย์ ถูกเพิกถอน หรือหมดอายุแล้ว (401)

### `insufficient_scope`

คีย์ไม่มีขอบเขตสิทธิ์ที่การเรียกนี้ต้องใช้ (403) เช่น `models:run` สำหรับการรัน หรือ `models:read` เพื่ออ่านคำขอและยอดคงเหลือ ดู [การตรวจสอบสิทธิ์](https://doitong.com/developers/docs/authentication#scopes)

### `account_disabled`

บัญชีถูกปิดหรือระงับ (403) คีย์ของบัญชีนั้นจะใช้งานไม่ได้อีกต่อไป

### `not_found`

ไม่มีพาธนี้อยู่ (404)

### `model_not_found`

ไม่มีโมเดลสาธารณะที่มีรหัสนี้ (404) แสดงรายการโมเดลด้วย `GET https://api.doitong.com/v1/models`

### `request_not_found`

ไม่มีคำขอที่มีรหัสนี้ในบัญชีของคุณ (404) คำขอของบัญชีอื่นจะไม่ปรากฏให้เห็น

### `insufficient_credits`

**ยอดคงเหลือ API** ของบัญชี (เครดิต API, 1,000 เครดิต API = $1 — ไม่ใช่เครดิตของแอป Doitong) ไม่ครอบคลุมราคาของการเรียกนี้ (402) ระบบจะส่งการตอบกลับก่อนเรียกเก็บเงินใด ๆ ข้อผิดพลาดนี้มี `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` ถูกใช้ไปแล้วกับบอดีอื่น (409) ใช้คีย์ใหม่สำหรับการดำเนินการใหม่

### `idempotency_in_progress`

กำลังสร้างคำขอที่มี `Idempotency-Key` เดียวกันอยู่ในขณะนี้ (409) รอสักครู่แล้วลองใหม่เพื่อรับคำขอ

### `request_active`

คำขอยังคงอยู่ในสถานะ `queued` หรือ `running` จึงยังไม่มีไฟล์ให้ลบ (409) ให้ลบไฟล์เมื่อคำขอเสร็จสิ้นแล้ว

### `not_cancelable`

คำขออยู่ในสถานะ `succeeded` หรือ `failed` แล้ว จึงไม่สามารถยกเลิกได้ (409)

### `rate_limited`

คีย์ส่งคำขอมากเกินไปในช่วงเวลาปัจจุบัน (429) ดูเฮดเดอร์ `X-RateLimit-*` และ `Retry-After`

### `too_many_inflight`

บัญชีมีคำขอ `queued` หรือ `running` อยู่แล้ว 10 รายการ (429) เริ่มรายการถัดไปเมื่อรายการใดรายการหนึ่งเสร็จสิ้น

### `upstream_error`

แบ็กเอนด์ของโมเดลปฏิเสธหรือทำคำขอล้มเหลว (502 ขณะรัน หรือคำขอมีโค้ดนี้เมื่ออยู่ในสถานะ `failed`) เครดิต API จะได้รับการคืนเงิน หากแบ็กเอนด์ปฏิเสธอินพุตเอง การเรียกจะส่งคืน `422 invalid_input` พร้อมข้อความของแบ็กเอนด์แทน

### `upstream_lost`

แบ็กเอนด์ของโมเดลไม่รู้จักคำขออีกต่อไป จึงจะไม่มีผลลัพธ์ส่งมา คำขอจะจบลงด้วยสถานะ `failed` และโค้ดนี้ (ชนิด `upstream_error`) พร้อมได้รับการคืนเงิน ให้รันอีกครั้ง

### `timeout`

คำขอทำงานนานเกินขีดจำกัด (15 นาทีสำหรับรูปภาพ, 60 นาทีสำหรับวิดีโอ, 30 นาทีสำหรับกรณีอื่น) จึงถูกหยุด คำขอจะจบลงด้วยสถานะ `failed` และโค้ดนี้ พร้อมได้รับการคืนเงิน

### `service_unavailable`

API หยุดชั่วคราว หรือการพึ่งพาบริการ เช่น การอัปโหลดไฟล์ ไม่พร้อมใช้งาน (503) ลองใหม่ภายหลัง

### `internal_error`

เกิดข้อผิดพลาดที่ฝั่งเรา (500) ลองใหม่ หากยังเกิดขึ้น โปรดติดต่อฝ่ายสนับสนุน

### `charge_failed`

ไม่สามารถเรียกเก็บเงินจากบัญชีได้เนื่องจากปัญหาภายใน (500) คำขอจะถูกทำเครื่องหมายเป็น `failed` และจะไม่มีการหักเงิน ลองใหม่

### `pricing_unavailable`

ยังไม่ได้กำหนดราคาของโมเดล จึงไม่สามารถเสนอราคาหรือรันได้ในขณะนี้ (500)