Trong quá trình gọi Gemini API bằng Python, Node.js hoặc các công cụ tự động hóa, việc thỉnh thoảng nhận lại thông báo lỗi là điều hiển nhiên. Đọc hiểu các mã lỗi (HTTP Status Codes) này là kỹ năng bắt buộc để khoanh vùng chính xác vấn đề nằm ở code của bạn hay do hệ thống của Google, từ đó có phương án sửa chữa kịp thời.

Bản chất vấn đề: Giao tiếp qua API tuân theo cơ chế Request (Yêu cầu) và Response (Phản hồi). Khi bạn gửi một Request, máy chủ Google sẽ kiểm tra định dạng, quyền truy cập và tài nguyên. Nếu có bất kỳ mắt xích nào bị sai lệch, máy chủ sẽ chặn lại và trả về một mã lỗi. Mã 4xx thường là lỗi do phía bạn (Client), còn mã 5xx là lỗi do hệ thống của Google (Server).

Dưới đây là bảng tổng hợp các nhóm lỗi cốt lõi và cách xử lý nhanh dựa trên tài liệu chính thức:

Mã lỗi Tên lỗi Nguyên nhân gốc rễ Cách khắc phục
400 INVALID_ARGUMENT Sai định dạng JSON, sai tên tham số, hoặc vượt giới hạn token. Lỗi do request gửi lên không hợp lệ. Kiểm tra lại cú pháp body request, đảm bảo truyền đúng tên biến và kiểu dữ liệu.
400 FAILED_PRECONDITION Môi trường chưa đủ điều kiện (VD: Dùng gói Free ở quốc gia không được hỗ trợ, hoặc chưa bật Billing). Bật Billing trong Google Cloud hoặc kiểm tra lại chính sách vùng của Free Tier.
401 UNAUTHENTICATED Hệ thống không nhận diện được bạn (thiếu API Key, token hết hạn hoặc sai header). Kiểm tra lại biến môi trường chứa API Key, đảm bảo truyền đúng định dạng Authorization header.
403 PERMISSION_DENIED Bạn đã đưa chìa khóa (API Key) nhưng chìa khóa đó không có quyền truy cập model cụ thể. Kiểm tra lại quyền của API Key/Project. Đảm bảo model bạn gọi không bị giới hạn quyền.
404 NOT_FOUND Gõ sai tên model (VD: gõ gemini-pro thay vì gemini-1.5-pro), sai endpoint hoặc file không tồn tại. Kiểm tra lại chính xác tên model và đường dẫn URL trên tài liệu API mới nhất.
429 RESOURCE_EXHAUSTED Gọi quá nhanh (vượt RPM) hoặc đã xài hết hạn mức (Quota) miễn phí. Giảm tần suất gửi request, áp dụng thuật toán chờ (delay) hoặc nâng cấp tài khoản.
500 / 503 INTERNAL / UNAVAILABLE Lỗi nội bộ hoặc máy chủ Google đang quá tải tạm thời. Không phải lỗi logic code của bạn. Chờ một khoảng thời gian ngắn rồi thử lại. Thử giảm bớt dung lượng đầu vào (context/prompt).
504 DEADLINE_EXCEEDED Context hoặc prompt quá dài, API không xử lý kịp trong thời gian cho phép. Cắt ngắn độ dài của prompt hoặc tăng thời gian timeout ở phía client của bạn.

Lưu ý/Lỗi thường gặp

  • Lỗi 429 xảy ra liên tục trong các vòng lặp: Nếu bạn viết script xử lý hàng loạt file, hãy luôn áp dụng cơ chế Exponential Backoff (tự động thử lại với thời gian chờ tăng dần: 1s, 2s, 4s...) khi gặp lỗi 429, 500, 503 để tránh bị hệ thống block.

  • Nhầm lẫn giữa 401 và 403: 401 là sai chìa khóa hoàn toàn, 403 là chìa khóa đúng nhưng không mở được cánh cửa bạn muốn.

  • Tên các Model Gemini thường xuyên được Google cập nhật và khai tử các bản cũ. Khi gặp lỗi 404, việc đầu tiên cần làm là tra cứu lại danh sách model hiện hành.

Truy cập vào trang tài liệu chính thức của Gemini API https://ai.google.dev/gemini-api/docs/models?hl=vi để xem danh sách các mô hình AI có sẵn.

Xử lý lỗi API hiệu quả tiết kiệm hàng giờ gỡ lỗi mò mẫm. Việc nắm rõ nhóm lỗi 4xx (sửa code của mình) và 5xx (chờ đợi server) kết hợp với các cơ chế tự động thử lại (retry) sẽ giúp các script tự động hóa của bạn hoạt động bền bỉ và chuyên nghiệp hơn.