Dành cho Lập trình viên & Tham chiếu API
Danh mục mã lỗi & Cách khắc phục
Đọc ~3 phút
401 Unauthorized — Xác thực không thành công
Nguyên nhân: Thiếu header Authorization, sai chuỗi mã khóa, hoặc khóa đã bị xóa/tắt trên Dashboard.
Cách xử lý:
Kiểm tra lại xem token có thừa khoảng trắng hay không. Đăng nhập Kandes Console để kiểm tra trạng thái khóa đang Bật.
402 Payment Required — Số dư ví không đủ
Nguyên nhân: Ví Kandes của tài khoản đã hết tiền (số dư = 0 ₫).
Cách xử lý:
Vào mục Nạp tiền quét mã VietQR. Sau khi nạp thành công bạn có thể gọi lại API ngay mà không cần khởi động lại ứng dụng.
404 Not Found — Không tìm thấy mô hình
Nguyên nhân: Tên model gửi lên không chính xác hoặc mô hình đang tạm bảo trì.
Cách xử lý:
Vào trang Danh mục mô hình, bấm nút sao chép tên model chính xác (ví dụ: claude-3-7-sonnet hoặc deepseek-r1).
429 Rate Limit — Chạm hạn mức chi tiêu
Nguyên nhân: Khóa API đã tiêu thụ hết số tiền trong ngày theo hạn mức bạn tự đặt.
Cách xử lý:
Vào mục Khóa API để nâng hạn mức hoặc chờ reset lúc 00:00 (giờ Việt Nam).
502 / 503 — Cụm máy chủ xử lý quá tải
Nguyên nhân: Mô hình bên phía cụm máy chủ gốc đang gặp sự cố gián đoạn tạm thời.
Cách xử lý:
Client của bạn nên tự động thử lại sau 2-3 giây (exponential backoff) hoặc chuyển sang model dự phòng cùng phân khúc.