Mã lỗi & Cách xử lý

Khắc phục lỗi request CometAPI với hướng dẫn đã được xác minh cho 400, 401 và lỗi path, cùng cách xử lý thực tế cho 403, 429 và các lỗi thuộc nhóm timeout.

Việc xử lý lỗi CometAPI sẽ dễ hơn khi bạn tách riêng lỗi request, lỗi xác thực, và các sự cố nền tảng có thể retry. Trang này là hướng dẫn lỗi chính thức của CometAPI và tập trung vào những gì bạn có thể xác minh từ phía client trước tiên.

Hướng dẫn này dựa trên các kiểm tra thực tế với API CometAPI hiện tại. Chúng tôi đã xác minh trực tiếp 400, 401, và các lỗi path/base URL. Chúng tôi không tái hiện 413, 429, 500, 503, 504, hoặc 524 trong các bài kiểm tra có giới hạn, vì vậy hướng dẫn cho các mã trạng thái đó được giữ ở mức thận trọng có chủ đích.

​

Phân loại nhanh

Status	Thường có nghĩa là gì	Retry?	Hành động đầu tiên
400	Xác thực request thất bại trước khi request được định tuyến thành công.	Không	Kiểm tra model, messages, cấu trúc JSON, và kiểu dữ liệu của các field.
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	Retry với một request chuẩn đã biết là hợp lệ và trước tiên loại bỏ các field đặc thù theo model.
Sai path	Sai base URL hoặc sai endpoint path. Trên Comet điều này có thể hiển thị thành 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 follow redirect khi debug.
429	Bị giới hạn tốc độ hoặc quá tải tạm thời.	Có	Dùng exponential backoff kèm jitter.
500, 503, 504, 524	Lỗi nền tảng hoặc lỗi thuộc nhóm timeout.	Có	Retry với backoff và giữ lại request id.

​

Error Envelope

JSON error envelope hiện tại do CometAPI trả về có dạng như sau:

{
	"error": {
		"code": "",
		"message": "...",
		"type": "comet_api_error"
	}
}

Nhiều thông báo lỗi thực tế cũng bao gồm request id bên trong error.message. Hãy lưu lại giá trị đó khi bạn cần hỗ trợ.

​

400 Bad Request

Những gì chúng tôi quan sát được từ API thực tế khi bỏ qua model:

{
	"error": {
		"code": "",
		"message": "model name is required (request id: ...)",
		"type": "comet_api_error"
	}
}

Trên thực tế, 400 thường có nghĩa là phần thân request không vượt qua bước xác thực trước khi nền tảng có thể định tuyến nó tới nhà cung cấp model.

Các nguyên nhân phổ biến:

• Thiếu các field bắt buộc như model hoặc messages
• Cấu trúc JSON không hợp lệ
• Gửi một field với sai kiểu dữ liệu
• Tái sử dụng các tham số riêng của nhà cung cấp mà endpoint đã chọn không chấp nhận

Cần làm gì:

1. Bắt đầu từ một request tối thiểu đã biết là hợp lệ.
2. Thêm lại các field tùy chọn từng cái một.
3. So sánh phần thân request với schema của endpoint trong tài liệu tham chiếu API.

Ví dụ tối thiểu đã biết là hợp lệ:

{
	"model": "your-model-id",
	"messages": [
		{
			"role": "user",
			"content": "Hello"
		}
	]
}

Thay your-model-id bằng bất kỳ model ID hiện tại nào từ trang Models của CometAPI.

​

401 Invalid Token

Những gì chúng tôi quan sát được từ API thực tế với key không hợp lệ:

{
	"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, shell history, hoặc kho secret trên môi trường triển khai.
3. Nếu một key bị lỗi nhưng một key khác hoạt động với cùng request, hãy xem đây là vấn đề token chứ không phải vấn đề endpoint.

​

403 Forbidden

Chúng tôi không tái hiện được một lỗi 403 ổn định trong các bài kiểm tra có giới hạn, vì vậy đừng xem một mẫu thông báo cũ đơn lẻ là toàn bộ bức tranh.

Trong tài liệu Comet hiện tại, 403 thường được nhắc đến trong một trong các tình huống sau:

• Yêu cầu 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 yêu cầu đượ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

Những việc nên làm trước:

1. Thử lại với một yêu cầu 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 theo provider, 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 xem chúng 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 khắc phục thực tế vẫn là xác thực token, model và dạng yêu cầu trước.

​

Sai Base URL Hoặc Sai Path

Đây là phần mà trang cũ kém chính xác nhất.

Trong các lần kiểm tra trực tiếp với các endpoint Comet hiện tại:

• Gửi yêu cầu đến https://api.cometapi.com/chat/completions trả về chuyển hướng 301 đến https://www.cometapi.com/chat/completions
• Gửi yêu cầu đến một route API giả như https://api.cometapi.com/v1/not-a-real-endpoint cũng trả về chuyển hướng 301 đến https://www.cometapi.com/v1/not-a-real-endpoint

Điều đó có nghĩa là lỗi path có thể xuất hiện dưới dạng:

• Một chuyển hướng
• Một phản hồi HTML không phải JSON nếu client của bạn đi theo chuyển hướng
• Một lỗi phân tích cú pháp bên trong SDK của bạn
• Một yêu cầu không bao giờ đến được lớp API một cách trọn vẹn

Hãy dùng chính xác base URL này:

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 đi theo chuyển hướng khi gỡ lỗi các vấn đề về path.

​

413 Request Entity Too Large

Chúng tôi không tái hiện được 413 trong một bài kiểm tra có giới hạn, ngay cả với phần thân yêu cầu JSON 8 MiB quá cỡ, vì vậy cách giải thích cũ rằng prompt quá dài là quá hẹp.

Nếu bạn thực sự gặp 413, trước tiên hãy xem đây là vấn đề về kích thước yêu cầu. Các nguyên nhân phổ biến gồm:

• Payload base64 lớn
• Ảnh hoặc âm thanh quá lớn được nhúng inline
• Multipart hoặc phần thân JSON rất lớn

Cần làm gì:

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 yêu cầu 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

Chúng tôi không tái hiện được 429 trong quá trình kiểm tra đồng thời có giới hạn với 24 yêu cầu song song GET /v1/models, vì vậy ngưỡng chính xác rõ ràng còn phụ thuộc vào route, model và trạng thái hiện tại của nền tảng.

Hãy xem 429 là lỗi có thể retry:

1. Sử dụng exponential backoff với jitter.
2. Giảm mức đồng thời của các đợt gửi dồn dập.
3. Bật ghi log yêu cầu để bạn có thể thấy route và model nào chạm ngưỡng đầu tiên.

Để tham khảo một mẫu retry có thể tái sử dụng, xem ví dụ backoff trong Chat Completions.

​

500, 503, 504, Và 524

Chúng tôi không tái hiện được các mã trạng thái này trong các bài kiểm tra có giới hạn. Chúng nên được ghi nhận là các lỗi phía server hoặc nhóm lỗi timeout, không phải lỗi do người dùng.

Hướng dẫn thực tế:

• 500: lỗi nội bộ của nền tảng hoặc phía provider
• 503: route hoặc dịch vụ provider tạm thời không khả dụng
• 504 và 524: các lỗi thuộc nhóm timeout giữa nền tảng, edge hoặc dịch vụ provider

Cần làm gì:

1. Retry với backoff.
2. Lưu lại request id, endpoint, model và mốc thời gian.
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 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
• Tên model
• Request body JSON đã được ẩn dữ liệu nhạy cảm (đây là mục hữu ích nhất cho 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
• Nội dung 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
• Mốc 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 ảnh, tải audio lên, tạo video, v.v.) thay vì chỉ nhận JSON body thông thường, hãy gửi payload tương đương đã được submit:

• Tên field và các 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, được tham chiếu qua URL hay được nhúng dưới dạng base64

Cách nhanh nhất để tái hiện một bug là payload request chính xác đã được ẩn dữ liệu 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 field cộng với metadata của tệp.

Điều này giúp rút ngắn đáng kể thời gian phản hồi của bộ phận hỗ trợ.