> ## Documentation Index
> Fetch the complete documentation index at: https://apidoc.cometapi.com/llms.txt
> Use this file to discover all available pages before exploring further.
# Xử lý mã lỗi
> Sử dụng hướng dẫn này để phân loại phản hồi lỗi CometAPI và áp dụng các bước thử lại hoặc khắc phục cho những lỗi request phổ biến.
Việc xử lý lỗi CometAPI sẽ dễ hơn khi bạn tách riêng **các vấn đề về cấu trúc request**, **các vấn đề về xác thực**, **lỗi đường dẫn**, và **các lỗi nền tảng có thể thử lại**. Hãy dùng kết hợp HTTP status, `error.code`, và `error.message` để quyết định nên sửa request hay thử lại.
## Phân loại nhanh
| Status | Thường có nghĩa là gì | Thử lại? | Hành động đầu tiên |
| --------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------- | --------------- | ------------------------------------------------------------------------------------------------ |
| `400` | Xác thực request thất bại trước khi request được xử lý bình thường. | Không | Kiểm tra `model`, `messages`, cấu trúc JSON, và kiểu dữ liệu của các trường. |
| `401` | API key bị thiếu, sai định dạng, hoặc không hợp lệ. | Không | Kiểm tra `Authorization: Bearer $COMETAPI_KEY`. |
| `403` | Quyền truy cập bị chặn hoặc request hiện tại không được phép. | Thường là không | Thử lại với một request đã biết là hợp lệ và trước tiên loại bỏ các trường dành riêng cho model. |
| Lỗi đường dẫn | Base URL hoặc đường dẫn endpoint bị sai. Trên Comet, lỗi này có thể xuất hiện dưới dạng chuyển hướng `301` hoặc HTML, thay vì JSON `404` rõ ràng. | Không | Dùng chính xác `https://api.cometapi.com/v1` và tắt tự động theo dõi redirect trong lúc debug. |
| `429` | Bị giới hạn tốc độ hoặc quá tải tạm thời. | Có | Sử dụng exponential backoff với jitter. |
| `500` với `error.code: invalid_request` | Một request sai định dạng xuất hiện dưới dạng phản hồi trạng thái phía server. | Không | Sửa request body trước khi thử lại. |
| `500`, `503`, `504`, `524` | Lỗi nền tảng, provider, hoặc nhóm lỗi timeout. | Có | Thử lại với backoff và giữ lại request id. |
## Cấu trúc bao lỗi
Nhiều lỗi của CometAPI sử dụng phần thân lỗi như sau:
```json theme={null}
{
"error": {
"message": "...",
"type": "comet_api_error",
"param": "",
"code": "invalid_request"
}
}
```
Một số phản hồi để trống `code`. Khi status là `500`, hãy xem `error.code` và `error.message` là tín hiệu quyết định.
## `400 Bad Request`
`400` thường có nghĩa là request body không vượt qua bước xác thực trước khi request có thể được xử lý bình thường.
Các nguyên nhân phổ biến:
* Thiếu các trường bắt buộc như `model`
* Cấu trúc JSON không hợp lệ
* Gửi một trường với sai kiểu dữ liệu
* Tái sử dụng các tham số dành riêng cho provider mà endpoint đã chọn không chấp nhận
Hãy bắt đầu từ một request tối giản đã biết là hợp lệ, rồi thêm lại các trường tùy chọn từng trường một. So sánh payload với schema của endpoint trong tài liệu tham chiếu API.
Sử dụng một request tối giản như sau:
```json theme={null}
{
"model": "your-model-id",
"messages": [
{
"role": "user",
"content": "Hello"
}
]
}
```
Thay `your-model-id` bằng bất kỳ model ID hiện có nào từ [trang Models của CometAPI](/vi/overview/models).
Đừng giả định rằng mọi chat request sai định dạng đều trả về `400`. Thiếu các trường chat bắt buộc như `messages` cũng có thể xuất hiện dưới dạng `500` với `error.code: invalid_request`.
## `500 Internal Server Error`
Phần lớn phản hồi `500` cho thấy lỗi nền tảng hoặc provider. Đối với Chat Completions, một số request sai định dạng cũng có thể xuất hiện dưới dạng `500` nhưng vẫn mang `error.code: invalid_request`.
Một ví dụ là request bỏ qua `messages`:
```json theme={null}
{
"error": {
"message": "field messages is required (request id: ...)",
"type": "comet_api_error",
"param": "",
"code": "invalid_request"
}
}
```
Nếu phản hồi `500` có `error.code: invalid_request`, hãy xem đó là vấn đề của request:
1. Sửa request body.
2. So sánh payload với schema của endpoint.
3. Chỉ thử lại sau khi đã sửa đúng payload.
Nếu phản hồi `500` không chỉ ra request không hợp lệ, hãy giữ lại `request id` và sử dụng backoff.
## `401 Invalid Token`
Lỗi token thường trông như thế này:
```json theme={null}
{
"error": {
"code": "",
"message": "invalid token (request id: ...)",
"type": "comet_api_error"
}
}
```
Những điều cần kiểm tra:
1. Header phải chính xác là `Authorization: Bearer $COMETAPI_KEY`.
2. Đảm bảo ứng dụng của bạn không tải một key cũ từ `.env`, lịch sử shell hoặc kho secret đã triển khai.
3. Nếu một key bị lỗi và một key khác hoạt động với cùng request đó, hãy xem đây là vấn đề token, không phải vấn đề endpoint.
## `403 Forbidden`
`403` thường là một trong các tình huống sau:
* Request bị chặn bởi một quy tắc phía nền tảng như lọc WAF
* Token hoặc route không được phép sử dụng model hoặc dạng request được yêu cầu
* Model được chọn từ chối một trong các tham số nâng cao mà bạn đã truyền vào
Việc nên làm trước tiên:
1. Thử lại với một request văn bản rất đơn giản trên một model đã biết là hoạt động tốt.
2. Xóa các trường nâng cao và tham số riêng của nhà cung cấp, sau đó thêm lại dần dần.
3. Nếu phản hồi có kèm request id, hãy lưu lại trước khi liên hệ bộ phận hỗ trợ.
Nếu thông báo nhắc đến các thuật ngữ nội bộ như `group` hoặc `channel`, hãy coi đó là chi tiết định tuyến, không phải thứ đầu tiên cần chẩn đoán từ phía client. Cách xử lý thực tế vẫn là kiểm tra token, model và dạng request trước.
## Sai base URL hoặc sai path
Trên Comet, lỗi path có thể xuất hiện dưới dạng:
* Một redirect
* Một phản hồi HTML không phải JSON nếu client của bạn tự động theo redirect
* Một lỗi phân tích cú pháp bên trong SDK của bạn
* Một request không bao giờ đến được tầng API một cách trọn vẹn
Hãy dùng chính xác base URL này:
```text theme={null}
https://api.cometapi.com/v1
```
Các bước kiểm tra được khuyến nghị:
1. Xác nhận rằng base URL có bao gồm `/v1`.
2. Xác nhận rằng path endpoint khớp chính xác với tài liệu.
3. Tắt tính năng tự động theo redirect khi debug các vấn đề về path.
## `413 Request Entity Too Large`
Nếu bạn thấy `413`, trước hết hãy xem đây là vấn đề về **kích thước request**. Các nguyên nhân thường gặp gồm:
* Payload base64 lớn
* Ảnh hoặc âm thanh quá lớn được nhúng inline
* Body multipart hoặc JSON rất lớn
Việc cần làm:
1. Giảm kích thước hoặc nén nội dung đính kèm.
2. Chia các tác vụ lớn thành các request nhỏ hơn.
3. Đừng cho rằng độ dài văn bản thuần là nguyên nhân duy nhất.
## `429 Too Many Requests`
Hãy coi `429` là lỗi có thể retry:
1. Sử dụng exponential backoff kèm jitter.
2. Giảm mức concurrency đột biến.
3. Bật logging request để bạn có thể thấy route và model nào bị bão hòa trước.
Để có một mẫu retry có thể tái sử dụng, xem ví dụ backoff trong [Chat Completions](/api/text/chat).
## `503`, `504`, và `524`
Các mã trạng thái này là các lỗi **phía máy chủ hoặc thuộc nhóm timeout**.
Hướng dẫn thực tế:
* `503`: route hoặc dịch vụ nhà cung cấp tạm thời không khả dụng
* `504` và `524`: lỗi thuộc nhóm timeout giữa nền tảng, edge hoặc dịch vụ nhà cung cấp
Việc cần làm:
1. Thử lại với backoff.
2. Lưu lại `request id`, endpoint, model và timestamp.
3. Nếu cùng một lỗi lặp lại qua nhiều lần retry, hãy liên hệ bộ phận hỗ trợ kèm theo ngữ cảnh đó.
## Trước khi bạn liên hệ bộ phận hỗ trợ
Hãy thu thập trước các thông tin sau:
* Phương thức HTTP
* Đường dẫn endpoint
* Model ID
* **JSON request body đã được ẩn thông tin nhạy cảm** (đây là mục hữu ích nhất trong hầu hết các lệnh gọi API)
* Query parameters nếu request bị lỗi có sử dụng chúng
* Response body chính xác nếu client của bạn đã ghi nhận được
* HTTP status đầy đủ
* `error.message` chính xác
* Bất kỳ `request id` nào
* Dấu thời gian ước lượng
* Liệu cùng request đó có hoạt động với model khác hoặc token khác hay không
Nếu route bị lỗi chấp nhận **tải tệp lên** (chỉnh sửa hình ảnh, tải âm thanh lên, tạo video, v.v.) thay vì chỉ một JSON body thuần, hãy gửi payload tương đương đã được submit:
* Tên các trường và giá trị văn bản bạn đã gửi kèm theo tệp
* Tên tệp, loại tệp và kích thước tệp ước lượng
* Tệp được tải lên trực tiếp, tham chiếu bằng URL hay được nhúng dưới dạng base64
Cách hiệu quả nhất để tái hiện một lỗi là payload request chính xác đã được ẩn thông tin nhạy cảm. Với hầu hết các lệnh gọi API, điều đó có nghĩa là **raw request body JSON**. Với các route tải tệp lên, điều đó có nghĩa là danh sách trường cộng với metadata của tệp.
Điều này sẽ rút ngắn đáng kể thời gian xử lý của bộ phận hỗ trợ.