Mã lỗi
401 / 403 / 404 / 429 / 5xx nghĩa là gì, quy trình chẩn đoán năm bước và cách thực hành giúp tránh lỗi.
Khi một lệnh gọi thất bại, hãy bắt đầu từ mã trạng thái HTTP và thông báo lỗi trong phần thân phản hồi, rồi đối chiếu với bảng dưới đây. Hầu hết vấn đề đều được giải quyết bằng ba mục đầu tiên.
Mã trạng thái
| Trạng thái | Ý nghĩa | Nguyên nhân thường gặp và cách xử lý |
|---|---|---|
| 400 Bad Request | Yêu cầu không hợp lệ | JSON sai định dạng hoặc thiếu trường bắt buộc (model, messages); đối chiếu phần thân với tài liệu API |
| 401 Unauthorized | Xác thực thất bại | Khóa sai / đã xóa / hết hạn; xem danh sách kiểm tra ở Xác thực |
| 403 Forbidden | Không có quyền truy cập | Khóa hoặc tài khoản này có thể không được gọi mô hình đã yêu cầu; xác nhận mô hình có khả dụng với bạn trong chợ mô hình |
| 404 Not Found | Không tìm thấy tài nguyên | Thường là do model ID viết sai; sao chép đúng ID từ chợ mô hình |
| 429 Too Many Requests | Bị giới hạn tốc độ | Yêu cầu quá dồn dập. Hãy giãn nhịp (khoảng cách tăng dần theo cấp số nhân) hoặc giảm số luồng đồng thời; liên hệ nền tảng nếu tình trạng kéo dài |
| 5xx | Lỗi phía máy chủ | Lỗi tạm thời của nền tảng hoặc của mô hình phía trên. Thử lại một lần với đúng tham số cũ; nếu vẫn lỗi liên tục, liên hệ Hỗ trợ kèm bản ghi yêu cầu từ trang nhật ký |
Các bước chẩn đoán
- Kiểm tra khóa: xác nhận trên trang "Khóa API" rằng khóa tồn tại và chưa hết hạn; xóa rồi tạo lại nếu không chắc.
- Kiểm tra model ID: sao chép từ chợ mô hình thay vì gõ tay.
- Đọc phần thân lỗi: phản hồi lỗi thường có
error.messagegiải thích nguyên nhân chính xác (số dư không đủ, thiếu tham số, ...). - Xem nhật ký: trang nhật ký trong bảng điều khiển hiển thị trạng thái, độ trễ và mức tiêu thụ của từng yêu cầu — xem lỗi có chỉ giới hạn ở một mô hình hay một khóa không.
- Vẫn bế tắc: liên hệ Hỗ trợ kèm mốc thời gian và mã trạng thái lấy từ trang nhật ký.
Thực hành giúp tránh lỗi
- Dùng SDK chính thức (nó xử lý sẵn việc thử lại, thời gian chờ và các chi tiết giao thức);
- Cài đặt giãn nhịp theo cấp số nhân cho 429 / 5xx thay vì thử lại liên tục;
- Đặt hạn mức chi tiêu cho khóa production để lưu lượng bất thường không rút cạn số dư.