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

​

Phân loại nhanh

​

Error Envelope

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

​

400 Bad Request

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

• 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

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.

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

​

401 Invalid Token

{
	"error": {
		"code": "",
		"message": "invalid token (request id: ...)",
		"type": "comet_api_error"
	}
}

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

• 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

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ợ.

​

Sai Base URL Hoặc Sai Path

• 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

• 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

https://api.cometapi.com/v1

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

• 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

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

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.

​

500, 503, 504, Và 524

• 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

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ợ

• 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

• 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