Gemini 503 “The model is overloaded” (UNAVAILABLE) — các lần thử lại có hiệu quả và khi nào nên dừng

“Mô hình đang quá tải” là lỗi Gemini duy nhất không liên quan đến bạn: cụm máy chủ phục vụ mô hình đó hiện không còn công suất. Không có thiết lập nào trong dự án có thể ngăn lỗi này — điều bạn có thể kiểm soát là cách xử lý khi lỗi xảy ra và phương án dự phòng bạn dùng khi lỗi không tự hết.

Lỗi

phản hồi (HTTP 503)

{
  "error": {
    "code": 503,
    "message": "The model is overloaded. Please try again later.",
    "status": "UNAVAILABLE"
  }
}

Tổng quan nguyên nhân và cách khắc phục

Nguyên nhân	Cách khắc phục
Nhu cầu tăng đột biến trên cụm máy chủ của mô hình đó	Backoff hàm mũ có jitter; đợt tăng đột biến thường qua trong vài giây đến vài phút.
Các biến thể mô hình preview / thử nghiệm	Các bản dựng -exp và preview chạy trên những cụm nhỏ nên quá tải trước. Hãy ghim bí danh ổn định cho môi trường production.
Yêu cầu nặng trong giờ cao điểm	Các ngữ cảnh rất lớn và giới hạn đầu ra tối đa dễ bị loại bỏ hơn khi hệ thống chịu tải — hãy cắt phần không cần thiết và stream phản hồi.

Xác nhận đây là 503 UNAVAILABLE, không phải 429

429 RESOURCE_EXHAUSTED là vấn đề hạn ngạch của bạn; 503 UNAVAILABLE là vấn đề công suất của Google. Phân biệt này quyết định mọi bước tiếp theo: lỗi hạn ngạch cần thay đổi thanh toán hoặc giới hạn, còn lỗi công suất cần retry và fallback. Đừng gỡ lỗi thiết lập dự án khi gặp 503 — không có gì cần tìm ở đó.

Retry với backoff — nhưng phải có ngân sách

503 về bản chất là lỗi có thể retry. Dùng cùng backoff hàm mũ có jitter như với mọi lỗi 429 (đoạn mã trong hướng dẫn Claude 429 của chúng tôi có thể dùng nguyên vẹn — nó đã retry các trạng thái nhóm 500), nhưng giới hạn tổng thời gian chờ ở mức mà caller có thể chịu được; một lỗi quá tải kéo dài sau khoảng 5 lần thử trong một phút sẽ không nhanh chóng tự hết.

Khi retry hết: đổi mô hình, không lặp vô hạn

Hãy chuẩn bị sẵn chuỗi fallback trước khi cần: bí danh ổn định nếu bạn đang dùng bản preview, gemini-2-5-flash nếu 2.5 Pro đang gặp sự cố (hoặc ngược lại), hoặc một nhà cung cấp hoàn toàn khác cho yêu cầu không được phép thất bại. Fallback biến sự cố thành việc suy giảm chất lượng.

Nếu bạn gọi qua Kunavo

Chế độ lỗi này là lý do Kunavo retry ngay trong request: khi một mô hình được cấu hình nhiều kênh upstream, một lần thử thất bại sẽ chuyển sang kênh còn lại trước khi bạn nhìn thấy lỗi — lỗi upstream tạm thời trở thành thành công chậm hơn thay vì 503 của bạn. Request thất bại không bao giờ bị tính phí, và vì một key dùng được cho Gemini, Claude và GPT, fallback liên nhà cung cấp ở bước 3 chỉ là thay đổi chuỗi mô hình thay vì tích hợp lần hai. Bạn đang cân nhắc mô hình fallback? Giá theo token của toàn bộ dòng Gemini, cùng với giá niêm yết của Google, có tại bảng giá Gemini API.

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

Các request trả về 503 có bị tính phí không?

Không — request bị từ chối trước khi suy luận, nên Google không tính phí; trên Kunavo, request thất bại cũng không bao giờ bị tính phí. Chi phí của 503 là độ trễ và retry, không phải token.

Lỗi quá tải Gemini kéo dài bao lâu?

Thường là vài giây đến vài phút; đợt tăng đột biến vào ngày ra mắt mô hình mới có thể kéo dài hơn. Vì vậy chính sách hợp lý là retry backoff vài lần, sau đó dùng mô hình fallback — không phải vòng lặp retry vô hạn.

Nâng cấp lên gói trả phí có ngăn được 503 không?

Không. Gói trả phí tăng hạn ngạch của bạn (nhóm lỗi 429), nhưng 503 UNAVAILABLE là công suất phục vụ dùng chung — lưu lượng miễn phí và trả phí đều gặp lỗi khi một cụm bị bão hòa. Fallback mới là biện pháp giảm thiểu, không phải thanh toán.

Hướng dẫn liên quan

Thông tin chi tiết hơn về ý nghĩa lỗi có trong tài liệu tham chiếu lỗi; bạn chỉ mất một phút để lấy khóa qua đăng ký và hướng dẫn xác thực.