Xử lý mã lỗi

​

Phân loại nhanh

​

Cấu trúc bao lỗi

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

​

400 Bad Request

• 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

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

​

500 Internal Server Error

{
	"error": {
		"message": "field messages is required (request id: ...)",
		"type": "comet_api_error",
		"param": "",
		"code": "invalid_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.

​

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, 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

• 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

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

​

Sai base URL hoặc sai path

• 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

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 theo redirect khi debug 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
• Body multipart hoặc 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 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

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.

​

503, 504, và 524

• 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

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ợ

• 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

• 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