# Lỗi

Nguồn: https://docs.aicentos.com/vi/billing/errors

Language: vi

> Mã trạng thái HTTP, cấu trúc phản hồi lỗi, lỗi thường gặp và cách xử lý

aicentos dùng hoàn toàn **định dạng phản hồi lỗi của OpenAI**. Khi SDK ném lỗi, chỉ cần catch exception tương ứng.

## Cấu trúc phản hồi lỗi

Mọi phản hồi lỗi đều theo định dạng này:

```bash
{
  "error": {
    "message": "API Key của bạn không có quyền truy cập gpt-5",
    "type": "permission_denied",
    "code": "model_not_allowed",
    "param": "model"
  }
}
```

| Trường    | Ý nghĩa                                            |
| --------- | -------------------------------------------------- |
| `message` | Mô tả lỗi dễ đọc cho người                         |
| `type`    | Loại lỗi (xem bảng dưới)                           |
| `code`    | Mã lỗi chi tiết (dùng để xử lý trong chương trình) |
| `param`   | Tên trường gây lỗi (nếu có)                        |

## Bảng tra nhanh mã trạng thái HTTP

| Mã trạng thái | Loại                     | Nguyên nhân thường gặp                                                        |
| ------------- | ------------------------ | ----------------------------------------------------------------------------- |
| `400`         | `invalid_request_error`  | Sai định dạng body, tham số không hợp lệ, gõ sai tên model                    |
| `401`         | `authentication_error`   | Thiếu / sai / đã bị thu hồi API Key                                           |
| `402`         | `insufficient_quota`     | Không đủ số dư                                                                |
| `403`         | `permission_denied`      | Key bị vô hiệu hóa, mô hình chưa được cấp quyền, IP không nằm trong whitelist |
| `404`         | `not_found`              | Sai đường dẫn endpoint, sai ID mô hình                                        |
| `408`         | `request_timeout`        | Upstream timeout (thường là không phản hồi > 60s)                             |
| `413`         | `payload_too_large`      | Body quá lớn (ảnh, tệp)                                                       |
| `415`         | `unsupported_media_type` | Sai Content-Type                                                              |
| `422`         | `invalid_request_error`  | Body parse được nhưng sai ngữ nghĩa                                           |
| `429`         | `rate_limit_exceeded`    | Chạm rate limit, giảm tần suất request rồi thử lại                            |
| `500`         | `server_error`           | Lỗi nội bộ nền tảng (hiếm gặp)                                                |
| `502`         | `bad_gateway`            | Dịch vụ upstream gặp sự cố                                                    |
| `503`         | `service_unavailable`    | Upstream quá tải, nên thử lại sau                                             |
| `504`         | `gateway_timeout`        | Upstream phản hồi vượt thời hạn                                               |

## Lỗi thường gặp và cách xử lý

### 401 — Invalid API key

```bash
{ "error": { "message": "Incorrect API key provided", "type": "authentication_error" } }
```

**Danh sách cần kiểm tra**:

* Header `Authorization` có đúng định dạng `Bearer sk-xxx` không (chú ý có dấu cách)
* Key có bị dính dấu cách / xuống dòng khi sao chép từ Console không
* Key đã bị xóa / vô hiệu hóa / hết hạn chưa
* Có lỡ dùng key test trên môi trường production không

### 402 — Insufficient quota

```bash
{ "error": { "message": "Insufficient quota", "type": "insufficient_quota" } }
```

Nạp tiền → Console, mục "Quản lý ví". Bật [cảnh báo số dư](https://docs.aicentos.com/vi/billing/pricing#c%E1%BA%A3nh-b%C3%A1o-s%E1%BB%91-d%C6%B0) để tránh tái diễn.

### 403 — Model not allowed

```bash
{ "error": { "message": "Model gpt-5 not allowed for this key", "code": "model_not_allowed" } }
```

Khi tạo token đã tick whitelist "Mô hình khả dụng", model yêu cầu không nằm trong đó. Sửa cài đặt token hoặc đổi Key.

### 404 — Model not found

```bash
{ "error": { "message": "The model 'gpt-4-turbo-2024-04-09' does not exist", "code": "model_not_found" } }
```

ID mô hình bị gõ sai hoặc đã ngừng cung cấp. Vào [thị trường mô hình](https://aicentos.com/pricing) để xác nhận ID hiện đang khả dụng.

### 429 — Rate limit exceeded

Header phản hồi `Retry-After` cho biết bao nhiêu giây sau nên thử lại. Giảm mức đồng thời và tần suất request là sẽ phục hồi.

### 500 / 502 / 503 — Lỗi dịch vụ

Thường do upstream chập chờn. **Tự động thử lại 2-3 lần** thường là thành công. Nếu kéo dài quá 5 phút:

* Xem [trang trạng thái](https://status.aicentos.com) (nếu có)
* Liên hệ bộ phận hỗ trợ

### 408 / 504 — Timeout

Request quá 60s không phản hồi. Nguyên nhân thường gặp:

* Prompt quá dài khiến mô hình "suy nghĩ" vượt thời gian
* Chưa bật streaming (phản hồi dài nên thêm `stream: true`)

**Cách xử lý**:

* Rút ngắn prompt
* Bật streaming: `{ "model": "...", "messages": [...], "stream": true }`
* Chuyển sang mô hình nhanh hơn (ví dụ từ `gpt-4o` sang `gpt-4o-mini`)

## Ví dụ xử lý lỗi trong SDK

```bash
export AICENTOS_API_KEY="sk-your-aicentos-api-key"
```

### Python

```python
import os
from openai import OpenAI, APIError, RateLimitError, AuthenticationError

client = OpenAI(api_key=os.environ["AICENTOS_API_KEY"], base_url="https://aicentos.com/v1")

try:
    resp = client.chat.completions.create(
        model="gpt-4o-mini",
        messages=[{"role": "user", "content": "hi"}],
    )
except AuthenticationError:
    print("Sai Key")
except RateLimitError as e:
    print(f"Bị rate limit, thử lại sau {e.response.headers.get('Retry-After')}s")
except APIError as e:
    print(f"Lỗi API khác: {e.status_code} {e.message}")
```

### Node.js

```js
import OpenAI, { APIError } from 'openai';

const client = new OpenAI({
  apiKey: process.env.AICENTOS_API_KEY,
  baseURL: 'https://aicentos.com/v1',
});

try {
  const resp = await client.chat.completions.create({ ... });
} catch (err) {
  if (err instanceof APIError) {
    console.log(err.status, err.code, err.message);
  }
}
```

## Khuyến nghị retry và giảm cấp

| Loại lỗi                              | Cách xử lý khuyến nghị                               |
| ------------------------------------- | ---------------------------------------------------- |
| `400` / `401` / `402` / `403` / `404` | **Không retry**, lỗi code / cấu hình, kiểm tra trước |
| `429`                                 | Retry theo `Retry-After`, backoff theo cấp số nhân   |
| `500` / `502` / `503` / `504` / `408` | Retry ngay 1-3 lần, cách nhau 1-5s                   |

SDK chính thức của OpenAI mặc định đã có chính sách retry hợp lý, **code production hãy dùng thẳng SDK, đừng tự fetch**.