# Mã lỗi

> Bảng mã lỗi của API KONG API AI: số trạng thái, mã lỗi, ý nghĩa và cách xử lý cho từng trường hợp.

Source: https://kongapiai.com/docs/errors

## Dạng của một lỗi

Mọi lỗi trả về JSON có cùng dạng:

```json
{"error": {"code": "key_limit", "message": "…"}}
```

Hãy xử lý theo `code`. Phần `message` dành cho người đọc và có thể đổi.

## Bảng mã lỗi

| Số | Mã | Ý nghĩa và cách xử lý |
| --- | --- | --- |
| 400 | `invalid_json` | Nội dung gửi lên không phải JSON hợp lệ. |
| 400 | `model_required` | Thiếu trường `model`. |
| 400 | `unknown_model` | Model không có trong danh mục. Xem [Model và giá](https://kongapiai.com/docs/models). |
| 401 | `unauthorized` | Thiếu khoá hoặc khoá không hợp lệ. |
| 402 | `key_limit` | Khoá đã chạm hạn mức tháng. Tăng hạn mức hoặc chờ đầu tháng. |
| 402 | `budget_exceeded` | Một hạn mức của thành viên, khách hàng hoặc không gian làm việc đã hết. |
| 402 | `insufficient_budget` | Số dư khả dụng không đủ để giữ trước chi phí tối đa của yêu cầu. Nạp thêm số dư. |
| 403 | `key_paused`, `key_revoked` | Khoá đang tạm dừng hoặc đã bị thu hồi. |
| 403 | `model_forbidden` | Model nằm ngoài các model khoá được dùng. |
| 403 | `application_disabled`, `customer_disabled` | Ứng dụng hoặc khách hàng đang bị tắt. |
| 404 | `not_found` | Địa chỉ không được hỗ trợ, hoặc không tìm thấy yêu cầu. |
| 409 | `duplicate_request` | Yêu cầu với `Idempotency-Key` này đã được nhận. Đọc trạng thái ở `/v1/requests/{id}`. |
| 409 | `idempotency_conflict` | Cùng `Idempotency-Key` nhưng nội dung khác. Dùng mã mới. |
| 413 | `body_too_large` | Nội dung vượt 2 MB. |
| 429 | `own_quota_unavailable` | Không nguồn riêng nào xử lý được và dự phòng bằng số dư đang tắt. |
| 429 | `tenant_rate_limit` | Gửi quá nhiều yêu cầu. Thử lại sau thời gian ghi trong header `Retry-After`. |
| 503 | `workspace_paused` | Quản trị viên đã tạm dừng mọi khoá. |
| 503 | `queue_timeout` | Không có nguồn phù hợp trong thời gian chờ. Thử lại sau. |
| 503 | `gateway_overloaded`, `draining` | Hệ thống đang đầy hoặc đang cập nhật. Thử lại sau vài giây. |

## Nên thử lại lỗi nào

- **Thử lại được:** `429` và `503`. Chờ theo `Retry-After` nếu có, và giữ nguyên `Idempotency-Key` để không bị tính hai lần.
- **Không thử lại:** `400`, `401`, `403`, `413`. Phải sửa yêu cầu hoặc khoá.
- **Cần người xử lý:** `402`. Tăng hạn mức hoặc nạp số dư.

## Yêu cầu lỗi có bị tính tiền không

Không. Yêu cầu lỗi không bị trừ số dư. Nếu chưa rõ kết quả, khoản tiền được giữ lại cho tới khi đối soát xong, rồi được trừ hoặc trả lại.
