> For the complete documentation index, see [llms.txt](https://docs.avis.net/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.avis.net/vi/tai-lieu-api/introduction/errors.md).

# Lỗi

### Mã trạng thái

| Mã trạng thái | Ý nghĩa                                                                                              |
| ------------- | ---------------------------------------------------------------------------------------------------- |
| `400`         | Bad request — thiếu/sai tham số, mô hình không được hỗ trợ, hoặc mô hình chưa được cấu hình giá      |
| `401`         | Unauthorized — API key bị thiếu, không hợp lệ hoặc không còn hoạt động (xem Xác thực)                |
| `403`         | Forbidden — số dư credit bằng 0 hoặc âm                                                              |
| `404`         | Not found — ví dụ: poll một video job ID không tồn tại                                               |
| `429`         | Too many requests — đã chạm giới hạn chi tiêu (ngày/tuần/tháng/tổng) do chủ sở hữu API key thiết lập |
| `500`         | Lỗi máy chủ nội bộ phía Avis                                                                         |
| `502` / `503` | Nhà cung cấp mô hình phía upstream gặp lỗi hoặc không khả dụng                                       |

### Hai dạng response lỗi

Lỗi có thể phát sinh từ hai nơi và **không** dùng chung một cấu trúc. Hãy lưu ý điều này khi viết mã xử lý lỗi.

#### 1. Lỗi phát sinh trước khi gọi upstream

Avis từ chối các lỗi xác thực, mô hình không được hỗ trợ/chưa có giá và số dư không đủ trước khi gửi request đến nhà cung cấp mô hình. Các lỗi này luôn có cùng một cấu trúc trên cả ba giao diện:

```json
{
  "errors": ["Insufficient credit balance"],
  "status": 403,
  "success": false,
  "path": "/api/openai/v1/chat/completions",
  "timestamp": 1751270603123
}
```

`errors` luôn là một mảng (kể cả khi chỉ có một thông báo). Đây là cấu trúc lỗi chung dùng trong toàn bộ ứng dụng, không phải định dạng riêng của OpenAI/Anthropic/Gemini.

#### 2. Lỗi do nhà cung cấp mô hình trả về

Sau khi request vượt qua bước kiểm tra xác thực và số dư, nó được gửi đến upstream. Mọi lỗi do nhà cung cấp trả về (như tham số không hợp lệ, sự cố phía nhà cung cấp hoặc từ chối theo chính sách nội dung) sẽ được chuyển lại cho bạn **nguyên vẹn**, với mã trạng thái và cấu trúc lỗi gốc. Ở bước này, Avis chỉ chuyển tiếp response.

**Giao diện OpenAI:**

```json
{
  "error": {
    "message": "The model 'openai/does-not-exist' does not exist",
    "type": "invalid_request_error",
    "code": "model_not_found"
  }
}
```

**Giao diện Anthropic:**

```json
{
  "type": "error",
  "error": { "type": "invalid_request_error", "message": "max_tokens: field required" }
}
```

**Giao diện Gemini:**

```json
{
  "error": { "code": 400, "message": "Invalid value at 'generation_config'", "status": "INVALID_ARGUMENT" }
}
```

Vì nhóm lỗi thứ hai phản ánh mọi lỗi do nhà cung cấp bên dưới trả về, các giá trị `type`/`code` thuộc về nhà cung cấp đó, không phải danh sách cố định do Avis định nghĩa.

### Lỗi trong khi streaming

**OpenAI `chat/completions`** sẽ stream một sự kiện lỗi ngay trong luồng nếu quá trình tạo thất bại giữa chừng, thay vì trả về lỗi HTTP thông thường (vì header `200` + SSE đã được gửi đi):

```
data: {"error":"upstream request failed"}
```

Sau sự kiện lỗi trong luồng sẽ không có `data: [DONE]`.

Stream của **Anthropic, Gemini và `/responses`** được chuyển thẳng từ nhà cung cấp upstream — nếu stream của nhà cung cấp chứa sự kiện lỗi, sự kiện đó sẽ đến theo định dạng gốc của nhà cung cấp; nếu kết nối upstream bị ngắt đột ngột, client chỉ đơn giản thấy stream kết thúc.

### Ví dụ để tái hiện lỗi

| Để thấy lỗi...               | Hãy làm như sau                                                                                    |
| ---------------------------- | -------------------------------------------------------------------------------------------------- |
| `401`                        | Bỏ header `x-api-key`, hoặc gửi một key đã bị thu hồi                                              |
| `403`                        | Gọi bất kỳ endpoint tạo nội dung nào khi số dư credit bằng 0/âm                                    |
| `400` (mô hình không hỗ trợ) | Gửi giá trị `model` không có trong danh mục Avis                                                   |
| `429`                        | Cấu hình giới hạn chi tiêu thấp cho key (`PATCH /api-keys/:keyId/usage-limit`), sau đó vượt quá nó |
| `404`                        | `GET /api/openai/v1/videos/:id` với một job ID tự đặt                                              |


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation by asking a question.

Perform an HTTP GET request on the following URL with the `ask` and `goal` query parameters:

```
GET https://docs.avis.net/vi/tai-lieu-api/introduction/errors.md?ask=<question>&goal=<user_goal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is what the user is ultimately trying to achieve, the reason they need the answer. Sharing it helps GitBook give you a better, more relevant answer. A goal is most helpful when it describes the outcome the user wants rather than restating the question. For example, with `ask=how do I create an API token`, a goal like `automate deployments from our CI pipeline` lets GitBook tailor the answer to that use case.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.