Lỗi 429 Gemini API: đổi API key không làm hạn mức quay về 0

Lỗi 429 RESOURCE_EXHAUSTED cho biết project gọi Gemini API đã chạm một giới hạn áp dụng chung. Đổi API key trong cùng project không đưa mức sử dụng về 0, vì hạn mức không được cấp riêng cho từng key.

Muốn xử lý đúng, bạn cần kiểm tra project, model và usage tier trong Google AI Studio, rồi xác định giới hạn bị chạm là RPM, TPM, RPD hay giới hạn chi tiêu. Chỉ retry khi tình trạng có thể tự hết; quota ngày, spend cap hoặc số dư Prepay cạn cần được xử lý theo nguyên nhân thay vì gửi lại liên tục.

Vì sao đổi API key không reset quota

API key là thông tin xác thực gắn với một project, không phải một kho quota độc lập. Tài liệu hạn mức Gemini API xác nhận rate limit được áp dụng theo project, thường gồm số request mỗi phút (RPM), token đầu vào mỗi phút (TPM) và request mỗi ngày (RPD); chỉ cần vượt một chiều là request có thể bị từ chối. RPD được đặt lại vào nửa đêm theo giờ Thái Bình Dương, còn giới hạn cụ thể phụ thuộc model và usage tier.

Do đó, hai key A và B thuộc cùng project P vẫn tiêu thụ chung hạn mức của P. Chuyển từ A sang B chỉ đổi credential được gửi lên máy chủ; thao tác này không tạo quota mới, không đổi tier và không xóa lượng request hoặc token đã ghi nhận.

Đổi key vẫn cần thiết nếu key cũ bị thu hồi, cấu hình sai hoặc lộ ra ngoài. Đây là biện pháp khắc phục sự cố xác thực hoặc bảo mật, không phải cách né giới hạn của project.

Cây quyết định cho RPM, TPM, RPD và chi tiêu

1. Xác nhận đúng project và model. Đối chiếu key mà tiến trình thực sự nạp khi chạy với project trong Google AI Studio. Kiểm tra chính xác model, bởi mỗi model có thể có hạn mức khác nhau và model experimental hoặc preview thường bị giới hạn chặt hơn.
2. Lỗi trùng với một đợt tăng số request: kiểm tra RPM. Nhiều worker, cron job khởi chạy cùng lúc hoặc vòng lặp song song có thể vượt trần phút dù tổng mức dùng trong ngày còn thấp. Giảm concurrency, đưa request vào hàng đợi và làm phẳng đợt tải.
3. Ít request nhưng prompt lớn: kiểm tra TPM. Một số ít request vẫn có thể vượt lượng token đầu vào cho phép trong một phút. Đo token trước khi gửi, rút gọn lịch sử hội thoại và giới hạn số prompt lớn chạy đồng thời.
4. Lỗi kéo dài dù đã giảm tốc độ: kiểm tra RPD. Quota ngày không phục hồi sau vài giây backoff. Nếu RPD đã cạn, hãy dừng retry cho đến chu kỳ đặt lại hoặc chuyển sang tier đáp ứng được tải thực tế.
5. Project trả phí và request tốn kém: kiểm tra giới hạn chi tiêu. Phân biệt rate limit dựa trên chi tiêu trong cửa sổ trượt với spend cap theo tháng, số dư Prepay và trạng thái billing. Đây là các điều kiện khác nhau; còn tiền không đồng nghĩa mọi giới hạn đều đang khả dụng.

Kiểm tra quota và billing trong Google AI Studio

Mở đúng project trong Google AI Studio, vào Dashboard > Usage và trang rate limits. Đối chiếu thời điểm phát sinh lỗi với model, RPM, TPM, RPD, số worker và kích thước prompt; số liệu tổng hợp cả ngày có thể che khuất một đợt tăng ngắn trong cửa sổ phút.

Với project trả phí, kiểm tra thêm Billing Tier, kế hoạch Prepay hoặc Postpay, số dư và spend cap. Hướng dẫn billing của Gemini API nêu rằng API key không có thiết lập thanh toán độc lập mà thừa hưởng tier, giới hạn và trạng thái billing của project; mức dùng từ mọi key trong project được cộng vào spend cap của project và tổng chi tiêu của billing account. Tài liệu này cũng cho biết số dư Prepay về 0 sẽ khiến mọi key trong các project liên kết với billing account đó ngừng hoạt động.

Không nên gộp hai lớp kiểm soát chi tiêu. Spend-based rate limit giới hạn tốc độ phát sinh chi phí trong một cửa sổ ngắn và có thể hết sau khi tải giảm; monthly spend cap chặn dịch vụ khi tổng chi tiêu đạt trần của chu kỳ. Tạo key mới không làm thay đổi lớp nào trong hai lớp này.

Retry an toàn bằng exponential backoff và jitter

Hướng dẫn troubleshooting của Google khuyến nghị exponential backoff có jitter, chỉ retry lỗi tạm thời như 429, 408 hoặc 5xx và đặt số lần thử tối đa; lỗi 400 hoặc 403 thường phải sửa key, quyền truy cập hoặc cú pháp request. Các SDK Gemini API chính thức đã có cơ chế retry tự động cho một số lỗi tạm thời, vì vậy cần kiểm tra cấu hình SDK trước khi bổ sung một lớp retry khác.

Với REST client tự quản lý retry, có thể dùng cấu hình khởi đầu do bài viết đề xuất dưới đây; các giá trị cần được điều chỉnh theo độ trễ mà ứng dụng chấp nhận:

1. Đặt maxAttempts = 5, gồm request đầu tiên; base delay là 1 giây và trần mỗi lần chờ là 32 giây.
2. Gửi request. Nếu thành công, trả kết quả; nếu mã lỗi không thuộc 429, 408 hoặc 5xx, dừng ngay và chuyển lỗi cho lớp xử lý phù hợp.
3. Với lỗi có thể retry, tính trần chờ của lần hiện tại bằng giá trị nhỏ hơn giữa 32 giây và 1 giây nhân 2 lũy thừa số lần đã thất bại.
4. Chọn ngẫu nhiên thời gian chờ từ 0 đến trần vừa tính để tạo jitter, sau đó mới gửi lại.
5. Dừng khi đạt maxAttempts. Không chuyển sang API key khác trong cùng project và không tạo vòng lặp vô hạn.

Chỉ đặt retry ở một lớp. Nếu SDK, reverse proxy và worker đều tự gửi lại, một request ban đầu có thể nhân thành nhiều request mới, làm RPM hoặc TPM cạn nhanh hơn. Với thao tác có side effect, cần thêm idempotency hoặc cơ chế chống xử lý trùng.

Biện pháp tương ứng với từng nguyên nhân

• Chạm RPM: giảm concurrency, dùng hàng đợi và phân tán thời điểm gửi.
• Chạm TPM: rút gọn context, đo token đầu vào và hạn chế prompt lớn chạy song song.
• Chạm RPD: dừng retry dồn dập, chờ chu kỳ đặt lại hoặc dùng tier phù hợp hơn.
• Chạm rate limit dựa trên chi tiêu: giảm tốc độ request đắt tiền, thu hẹp context hoặc output và chờ cửa sổ trượt dịch chuyển.
• Hết số dư hoặc chạm spend cap: xử lý billing; đổi key không có tác dụng.
• Không thấy giới hạn nào bị vượt: lưu thời điểm, model, project, mã trạng thái, request ID nếu có và nội dung lỗi đã loại bỏ dữ liệu nhạy cảm để phục vụ điều tra.

Điểm phân biệt quan trọng là backoff chỉ giúp khi giới hạn có thể tự giải phóng sau một khoảng chờ. Nó không reset quota ngày, đổi usage tier, bổ sung số dư hay mở lại một spend cap đã cạn.

Đọc thêm:

• Gemini Enterprise thêm trần chi tiêu: AI agent hết ngân sách sẽ tự dừng
• Gemini Enterprise thêm trả theo mức dùng: hết cảnh mua ghế rồi để trống?
• Gắn nhãn “remote” chưa đủ: chỉ 2,2–12,4% việc làm không giới hạn nơi ở