Lỗi Gemini API: xử lý 401, 404, 429 và giới hạn khu vực (2026)

Lỗi của Gemini API nhìn có vẻ nhiều tên, nhưng khi điều tra thực tế phần lớn rơi vào bốn loại: danh tính sai, địa chỉ sai, hạn mức không đủ, mạng không tới được. Vấn đề thực sự do bản thân mô hình gây ra lại ít hơn.

Bài viết phân loại theo mã lỗi, đưa ra một thứ tự điều tra bắt đầu từ yêu cầu tối thiểu. Khi gặp sự cố, trước hết lưu toàn bộ JSON lỗi, rồi đối chiếu theo thứ tự, không sửa đồng thời Key, địa chỉ và mô hình.

Lưu ý: Google và Gemini là nhãn hiệu của chủ sở hữu tương ứng. Bài viết lấy hình thái giao diện phổ biến tháng 10 năm 2026 làm ví dụ; phiên bản giao diện, hạn mức và chính sách khu vực căn cứ theo tài liệu chính thức và giá mô hình trên site.

1. Trước hết học cách đọc phần thân lỗi

Lỗi của Google API thường trả về JSON, có ba trường then chốt:

{
  "error": {
    "code": 429,
    "message": "Quota exceeded for quota metric ...",
    "status": "RESOURCE_EXHAUSTED"
  }
}

code là mã trạng thái HTTP, status là loại lỗi máy đọc được, message thường chứa nguyên nhân cụ thể, details có thể chứa quota ID và thời điểm thử lại đề xuất. Khi điều tra phải xem cả ba; chỉ nhìn "429" sẽ bỏ lỡ việc "rốt cuộc là giới hạn theo phút hay đã hết hạn mức ngày".

Mã trạng thái	status thường gặp	Hướng đại khái
401	UNAUTHENTICATED	Thiếu Key, Key không hợp lệ hoặc đặt sai chỗ
403	PERMISSION_DENIED	Dự án chưa bật, quyền hoặc khu vực bị hạn chế
404	NOT_FOUND	Tên mô hình, đường dẫn giao diện hoặc phiên bản sai
429	RESOURCE_EXHAUSTED	Vượt tốc độ, đồng thời hoặc hạn mức
400	INVALID_ARGUMENT / FAILED_PRECONDITION	Tham số sai, khu vực không hỗ trợ, điều kiện tiên quyết không đủ
500/503	INTERNAL / UNAVAILABLE	Sự cố tạm thời thượng nguồn, thường có thể lùi và thử lại

2. 401: Key không hợp lệ hoặc cách xác thực sai

Cốt lõi của 401 là "máy chủ không nhận ra danh tính của bạn". Nguyên nhân phổ biến:

Yêu cầu không mang Key, hoặc biến môi trường rỗng.
Giao diện gốc dùng Authorization thay vì x-goog-api-key.
Giao diện tương thích OpenAI dùng x-goog-api-key thay vì Authorization: Bearer.
Key có khoảng trắng, xuống dòng ở đầu cuối, hoặc bị dính dấu ngoặc khi sao chép.
Key đã bị xóa, luân chuyển, hoặc dự án chứa nó bị vô hiệu hóa.
Gửi Key của cổng đến địa chỉ chính thức của Google, hoặc ngược lại.
Key đặt giới hạn API, không cho phép gọi Gemini API.

Trước hết dùng một yêu cầu tối thiểu để xác nhận:

export GEMINI_API_KEY="khoa-cua-ban"

# Giao diện Gemini gốc
curl "https://generativelanguage.googleapis.com/v1beta/models/<model-id>:generateContent" \
  -H "x-goog-api-key: $GEMINI_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"contents":[{"parts":[{"text":"Chỉ trả lời OK"}]}]}'

# Giao diện tương thích OpenAI
curl "https://generativelanguage.googleapis.com/v1beta/openai/chat/completions" \
  -H "Authorization: Bearer $GEMINI_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"model":"<model-id>","messages":[{"role":"user","content":"Chỉ trả lời OK"}]}'

Hai lệnh tương ứng hai kiểu xác thực. Lệnh nào chạy thông cho biết Key và địa chỉ của bạn thuộc hệ thống nào; khi dùng lẫn mà gặp 401 thì không phải Key hỏng, mà là ghép sai.

3. 404: tên mô hình, đường dẫn hoặc phiên bản sai

404 không nhất thiết là "mô hình không tồn tại". Các trường hợp phổ biến:

ID mô hình viết sai, hoặc dùng tên hiển thị trên bảng điều khiển thay vì định danh API.
Mô hình không thuộc phiên bản API hiện tại, ví dụ gửi mô hình chỉ mở ở bản mới vào đường dẫn bản cũ.
Base URL thừa hoặc thiếu /v1, /v1beta, sau khi ghép thành địa chỉ không tồn tại.
Địa chỉ có thêm dấu gạch chéo ở cuối, máy khách lại ghép thêm một lần đường dẫn.
Khi gọi qua cổng, mô hình đó chưa được mở trong nhóm hoặc gói hiện tại.
Dùng giao diện trò chuyện để gọi tạo ảnh hoặc giao diện chuyên dụng khác.

Khi điều tra, trước hết liệt kê các mô hình mà Key hiện tại dùng được:

curl "https://generativelanguage.googleapis.com/v1beta/models" \
  -H "x-goog-api-key: $GEMINI_API_KEY"

Nếu danh sách có mô hình mục tiêu, hãy đối chiếu đường dẫn yêu cầu; nếu không có, hãy giải quyết vấn đề mở mô hình hoặc quyền trước. Khi gọi qua cổng, căn cứ theo ID mô hình và Base URL trong tài liệu cổng, không áp thẳng tên mô hình chính thức.

4. 429: phân biệt giới hạn tốc độ hay hết hạn mức

429 là loại dễ bị đánh giá sai nhất. Nó ít nhất gồm ba trường hợp:

Loại	Đặc điểm điển hình	Hướng xử lý
Giới hạn theo phút	Đồng thời cao trong thời gian ngắn, lỗi tập trung trong vài giây	Giảm đồng thời, lùi và thử lại
Hết hạn mức ngày	Lượng gọi trong ngày đạt giới hạn, thất bại liên tục	Đợi đặt lại, nâng hạn mức hoặc đổi phương án
Hạn mức cấp dự án	Nhiều dịch vụ dùng chung một dự án, chiếm của nhau	Tách dự án, tách Key, hạn mức riêng

details trong phần thân lỗi thường cho quota ID và thời điểm thử lại đề xuất. Đừng thấy 429 là gửi lại ngay; bão thử lại sẽ làm tình hình tệ hơn. Trước hết cài phụ thuộc: pip install requests. Một logic lùi khả dụng:

import random
import time
import requests

def generate(prompt: str, retries: int = 4):
    url = "https://generativelanguage.googleapis.com/v1beta/models/<model-id>:generateContent"
    headers = {
        "x-goog-api-key": "khoa-cua-ban",
        "Content-Type": "application/json",
    }
    for attempt in range(retries):
        resp = requests.post(
            url,
            headers=headers,
            json={"contents": [{"parts": [{"text": prompt}]}]},
            timeout=60,
        )
        if resp.status_code == 200:
            return resp.json()
        if resp.status_code not in (429, 500, 503):
            resp.raise_for_status()
        wait = min(2 ** attempt, 30) + random.random()
        time.sleep(wait)
    raise RuntimeError("Đã dùng hết số lần thử lại")

Thử lại chỉ giải quyết tắc nghẽn tạm thời, không giải quyết hết hạn mức. Môi trường sản xuất còn phải thêm thời gian chờ, cầu chì và mô hình dự phòng, nếu không một lần 429 sẽ kéo sập cả chuỗi.

5. Giới hạn khu vực: vì sao kết nối trực tiếp trong nước thất bại

Gemini API chỉ cung cấp dịch vụ ở một số quốc gia và khu vực. Khi đầu ra yêu cầu rơi vào khu vực không được hỗ trợ, thường có ba biểu hiện:

Quá thời gian kết nối hoặc bắt tay TLS thất bại, thường do đường mạng không thông.
Trả 400 FAILED_PRECONDITION, nội dung có nhắc location is not supported.
Trả 403 PERMISSION_DENIED, có thể liên quan dự án, thanh toán hoặc quyền khu vực.

Ở đây có hai khái niệm dễ nhầm: khu vực đăng ký tài khoản và khu vực đầu ra yêu cầu. Kể cả tài khoản dùng được, nếu máy chủ triển khai ở khu vực không hỗ trợ, yêu cầu vẫn có thể bị từ chối; ngược lại, proxy trên máy cá nhân mở được trang web không có nghĩa yêu cầu API đi cùng tuyến đó.

Thứ tự xử lý đề xuất:

Xác nhận yêu cầu phát ra từ máy cá nhân, container hay máy chủ, tìm IP đầu ra thực tế.
Đối chiếu khu vực đầu ra có nằm trong danh sách chính thức hỗ trợ không.
Kiểm tra lựa chọn khu vực của máy chủ đám mây, chuyển sang khu vực hỗ trợ nếu cần.
Nếu nghiệp vụ chủ yếu trong nước, đánh giá tích hợp qua cổng tuân thủ, xử lý thống nhất mạng và hóa đơn.
Đừng coi "đổi IP" là phương án duy nhất; trước hết xác nhận điều khoản dịch vụ và yêu cầu pháp luật địa phương.

6. Các lỗi phổ biến khác

Hiện tượng	Nguyên nhân thường gặp	Xử lý
400 INVALID_ARGUMENT	Cấu trúc JSON sai, thứ tự vai trò sai, định dạng ảnh không hỗ trợ	Dùng yêu cầu tối thiểu thêm trường từng bước
400 FAILED_PRECONDITION	Khu vực không hỗ trợ, chưa mở thanh toán, thiếu điều kiện tiên quyết	Kiểm tra khu vực, thanh toán và trạng thái dự án
403 PERMISSION_DENIED	API chưa bật, Key bị hạn chế, quyền dự án không đủ	Bật trong bảng điều khiển và đối chiếu quyền
500 INTERNAL	Lỗi nội bộ thượng nguồn	Lùi và thử lại, ghi request ID
503 UNAVAILABLE	Thượng nguồn quá tải hoặc bảo trì	Lùi và thử lại, chuyển mô hình dự phòng
Có phản hồi nhưng không có nội dung	Chính sách an toàn chặn, đầu ra bị cắt	Xem blockReason và finishReason
Đầu ra dừng giữa chừng	Đạt Token đầu ra tối đa	Tăng giới hạn hoặc rút ngắn đầu vào

"Có phản hồi nhưng không có nội dung" thường bị coi là sự cố, thực ra là lọc an toàn hoặc giới hạn độ dài. Trước hết xem promptFeedback.blockReason, finishReason và usageMetadata trong phản hồi, rồi mới quyết định sửa prompt hay điều chỉnh tham số.

7. Thứ tự điều tra đề xuất

Lưu toàn bộ JSON lỗi, thời điểm yêu cầu, ID mô hình và request ID.
Dùng curl gửi một yêu cầu tối thiểu, loại bỏ ảnh hưởng của máy khách và SDK.
Đối chiếu ba thứ: Base URL, header xác thực, ID mô hình.
Đổi sang một mô hình đã biết dùng được, xác định là vấn đề mô hình hay chuỗi kết nối.
Xem hạn mức, thanh toán và trạng thái dự án, phân biệt 429 với 403.
Xác nhận khu vực đầu ra và đường mạng của yêu cầu.
Cuối cùng mới kiểm tra cấu hình máy khách, cài đặt proxy và logic thử lại trong mã.

Mỗi lần chỉ đổi một biến. Nếu không, kể cả khi khôi phục được cũng không biết bước nào đã sửa, lần sau vẫn dẫm lại hố cũ.

8. Câu hỏi thường gặp

401 và 403 khác nhau thế nào?

401 là "danh tính chưa qua", ưu tiên kiểm tra Key, header xác thực và địa chỉ có khớp không; 403 là "danh tính đã qua nhưng không có quyền", ưu tiên kiểm tra API có bật không, quyền dự án, giới hạn Key và chính sách khu vực.

429 đợi vài phút rồi thử lại là được à?

Phải xem loại hạn mức. Giới hạn theo phút thường khôi phục sau khi lùi; hết hạn mức ngày phải đợi đặt lại hoặc nâng hạn mức. Trước hết đọc quota ID và đề xuất thử lại trong phần thân lỗi, đừng gửi lại mù quáng.

Giới hạn khu vực đổi IP là giải quyết được à?

Không nhất định. Phải xem khu vực đầu ra thực tế, trạng thái tài khoản và điều khoản dịch vụ. Với kịch bản doanh nghiệp, cách ổn định hơn là chọn khu vực được hỗ trợ để triển khai, hoặc tích hợp thống nhất qua cổng tuân thủ.

Địa chỉ chính thức chạy thông, đổi sang cổng báo 404, lỗi của ai?

Trước hết đối chiếu Base URL và ID mô hình của cổng. Cách đặt tên mô hình, đường dẫn và phạm vi khả dụng của cổng có thể khác chính thức, không thể áp thẳng yêu cầu chính thức. Dùng ví dụ tối thiểu trong tài liệu cổng để thay thế từng mục.

Làm sao tránh thử lại làm tăng chi phí?

Đặt số lần thử lại tối đa, lùi cấp số nhân và thời gian chờ; xử lý riêng 429; thêm loại bỏ trùng lặp cho yêu cầu không lũy đẳng; đặt giới hạn ngân sách và cảnh báo phía cổng.

Bước tiếp theo

Điểm then chốt khi điều tra lỗi Gemini là phân biệt bốn loại "xác thực, đường dẫn, hạn mức, mạng" trước, rồi dùng yêu cầu tối thiểu xác minh từng mục. Nếu cần điểm vào thống nhất, giảm bất định của kết nối trực tiếp trong nước, có thể đăng ký ZSQH AI Gateway; mô hình, hạn mức và giá căn cứ theo bảng giá mô hình.