# Lỗi

Mọi điểm cuối đều lỗi theo cùng một cách: mã trạng thái HTTP và một phong bì 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"
  }
}
```

| Trường | Ý nghĩa |
|---|---|
| `type` | Phân loại rộng của lỗi. Dựa vào đây để quyết định cách xử lý. |
| `code` | Lý do chính xác, ổn định và máy có thể đọc. Mỗi mã có một phần bên dưới; `doc_url` liên kết đến phần đó. |
| `message` | Giải thích để con người đọc, an toàn để ghi nhật ký hoặc hiển thị cho nhà phát triển. |
| `param` | Tham số đầu vào hoặc header gây lỗi, nếu có. |
| `details` | Với lỗi đầu vào, mọi vấn đề được tìm thấy: `[{ "param", "message" }]`. |
| `request_id` | Yêu cầu liên quan, nếu có. |

Không tính phí cho cuộc gọi trả về lỗi. Yêu cầu lỗi *sau khi* được chấp nhận vẫn có trạng thái
`failed`, chứa `error: { "type", "code", "message" }` trong đối tượng yêu cầu và được hoàn tiền tự động.

## Loại

| Loại | Trạng thái HTTP | Cách xử lý |
|---|---|---|
| `invalid_request` | 400, 413 hoặc 422 | Sửa yêu cầu. Gửi lại cùng cuộc gọi sẽ tiếp tục lỗi. |
| `authentication_error` | 401 | Gửi khóa hợp lệ trong `Authorization: Bearer <key>`. |
| `permission_error` | 403 | Dùng khóa có scope cần thiết. |
| `not_found` | 404 | Kiểm tra id mô hình hoặc id yêu cầu. |
| `insufficient_credits` | 402 | Nạp tiền vào số dư API (`top_up_url` trong lỗi). |
| `budget_exceeded` | 402 | Ngân sách riêng của khóa đã dùng hết. Cuối cùng: yêu cầu chủ sở hữu khóa tăng ngân sách. |
| `conflict` | 409 | Tài nguyên không ở trạng thái cho phép cuộc gọi này. |
| `rate_limited` | 429 | Chờ `Retry-After` giây rồi thử lại. |
| `upstream_error` | 502 | Backend mô hình lỗi. Có thể thử lại với cùng `Idempotency-Key`: yêu cầu sẽ chạy lại; bạn không bị tính phí. |
| `service_unavailable` | 503 | API đang tạm dừng hoặc một phần phụ thuộc đang ngừng hoạt động. Thử lại sau. |
| `internal_error` | 500 | Lỗi phía chúng tôi. Thử lại; nếu vẫn tiếp diễn, liên hệ bộ phận hỗ trợ kèm thời gian và `request_id`. |

## Mã lỗi

### `invalid_request`

Yêu cầu không đúng định dạng (400).

### `invalid_json`

Phần thân không phải JSON hợp lệ (400).

### `invalid_body`

Phần thân là JSON hợp lệ nhưng không phải đối tượng; đầu vào mô hình phải là một đối tượng JSON (400).

### `body_too_large`

Phần thân lớn hơn 16 MB (413). Tải tệp lớn lên và truyền URL của chúng thay vào đó (xem [Tệp](https://doitong.com/developers/docs/files)).

### `invalid_parameter`

Một tham số truy vấn có giá trị sai, chẳng hạn `limit` nằm ngoài 1 đến 100, `wait` không phải số, `status` hoặc `category` không xác định, hoặc `storage` khác `permanent` / `temporary` (400). `param` cho biết tham số đó.

### `invalid_category`

`GET /openapi.json?category=` chỉ định một danh mục không tồn tại (400). `GET https://api.doitong.com/v1/categories` liệt kê các danh mục.

### `invalid_cursor`

`cursor` của cuộc gọi danh sách không thuộc danh sách này (400). Bắt đầu lại mà không dùng cursor.

### `invalid_idempotency_key`

Header `Idempotency-Key` trống hoặc dài hơn 255 ký tự (400).

### `invalid_arguments`

Một cuộc gọi công cụ MCP thiếu đối số hoặc có đối số sai định dạng (chỉ MCP). `param` cho biết đối số đó.

### `invalid_input`

Đầu vào mô hình không vượt qua kiểm tra xác thực (422): tham số không xác định (thông báo gợi ý tên hợp lệ gần nhất), tham số bắt buộc bị thiếu, sai kiểu, giá trị nằm ngoài danh sách hoặc phạm vi cho phép, hoặc đồng thời cung cấp tên chuẩn và tên gốc với các giá trị khác nhau. `param` là tham số lỗi đầu tiên và `details` liệt kê tất cả. Không tính phí.

### `unsupported_file`

Một tệp có kiểu không được chấp nhận (422), chẳng hạn tệp tải lên có phần mở rộng không hỗ trợ hoặc `content_type` không khớp với phần mở rộng.

### `invalid_webhook_url`

`webhook_url` không phải URL công khai `https://` (422). Địa chỉ riêng tư, cục bộ và `http://` thuần túy bị từ chối.

### `missing_api_key`

Điểm cuối yêu cầu khóa API nhưng không nhận được khóa nào (401).

### `invalid_api_key`

Khóa không xác định, đã bị thu hồi hoặc hết hạn (401).

### `insufficient_scope`

Khóa thiếu scope mà cuộc gọi cần (403), chẳng hạn `models:run` để chạy hoặc `models:read` để đọc yêu cầu và số dư. Xem [Xác thực](https://doitong.com/developers/docs/authentication#scopes).

### `account_disabled`

Tài khoản đã đóng hoặc bị đình chỉ (403). Các khóa của tài khoản không còn hoạt động.

### `not_found`

Đường dẫn không tồn tại (404).

### `model_not_found`

Không có mô hình công khai nào có id này (404). Liệt kê mô hình bằng `GET https://api.doitong.com/v1/models`.

### `request_not_found`

Không có yêu cầu nào có id này trong tài khoản của bạn (404). Yêu cầu của tài khoản khác không bao giờ hiển thị.

### `insufficient_credits`

**Số dư API** của tài khoản (tín dụng API, 1.000 tín dụng API = 1 $ — không phải tín dụng của các ứng dụng Doitong) không đủ trả giá cuộc gọi này (402). Phản hồi được gửi trước khi tính phí. Lỗi chứa `top_up_url`; thêm tiền tại [https://doitong.com/developers/dashboard#balance](https://doitong.com/developers/dashboard#balance) rồi thử lại.

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

Cuộc gọi sẽ vượt quá ngân sách riêng của khóa API tính bằng tín dụng API (402). Ngân sách do chủ sở hữu khóa đặt; thử lại không có tác dụng cho đến khi họ tăng ngân sách.

### `conflict`

Cuộc gọi xung đột với trạng thái hiện tại của tài nguyên (409).

### `idempotency_mismatch`

`Idempotency-Key` đã được dùng với phần thân khác (409). Dùng khóa mới cho thao tác mới.

### `idempotency_in_progress`

Một yêu cầu có cùng `Idempotency-Key` đang được tạo (409). Chờ một lát rồi thử lại để nhận yêu cầu đó.

### `request_active`

Yêu cầu vẫn đang `queued` hoặc `running`, nên chưa có tệp để xóa (409). Xóa chúng sau khi yêu cầu hoàn tất.

### `not_cancelable`

Yêu cầu đã `succeeded` hoặc `failed` và không thể hủy (409).

### `rate_limited`

Khóa đã tạo quá nhiều yêu cầu trong khoảng thời gian hiện tại (429). Xem các header `X-RateLimit-*` và `Retry-After`.

### `too_many_inflight`

Tài khoản đã có 10 yêu cầu `queued` hoặc `running` (429). Bắt đầu yêu cầu tiếp theo khi một yêu cầu hoàn tất.

### `upstream_error`

Backend mô hình từ chối hoặc làm lỗi yêu cầu (502 khi chạy, hoặc yêu cầu có trạng thái `failed` với mã này). Tín dụng API được hoàn tiền. Nếu chính backend từ chối đầu vào, cuộc gọi trả về `422 invalid_input` cùng thông báo của backend.

### `upstream_lost`

Backend mô hình không còn biết yêu cầu, nên sẽ không bao giờ có kết quả. Yêu cầu kết thúc ở trạng thái `failed` với mã này (kiểu `upstream_error`) và được hoàn tiền. Chạy lại yêu cầu.

### `timeout`

Yêu cầu chạy lâu hơn giới hạn (15 phút cho hình ảnh, 60 cho video, 30 cho các loại khác) và bị dừng. Yêu cầu kết thúc ở trạng thái `failed` với mã này và được hoàn tiền.

### `service_unavailable`

API tạm thời bị dừng hoặc một phần phụ thuộc như tải tệp đang ngừng hoạt động (503). Thử lại sau.

### `internal_error`

Đã xảy ra lỗi phía chúng tôi (500). Thử lại; nếu vẫn tiếp diễn, liên hệ bộ phận hỗ trợ.

### `charge_failed`

Không thể tính phí tài khoản do vấn đề nội bộ (500). Yêu cầu được đánh dấu `failed`; không khoản nào bị trừ. Thử lại.

### `pricing_unavailable`

Giá của mô hình chưa được cấu hình, nên hiện không thể báo giá hoặc chạy mô hình (500).