Trang này cung cấp thông tin khắc phục sự cố về các mã lỗi thường gặp cho SDK Gemini API và Firebase AI Logic.
Lỗi 400: API key not valid. Please pass a valid API key.
Nếu bạn nhận được lỗi 400 có nội dung API key not valid. Please pass a valid API key., thì thường là do khoá API trong tệp/đối tượng cấu hình Firebase của bạn không tồn tại hoặc chưa được thiết lập để dùng với ứng dụng và/hoặc dự án Firebase.
Kiểm tra để đảm bảo khoá API có trong tệp/đối tượng cấu hình Firebase khớp với khoá API của ứng dụng. Bạn có thể xem tất cả khoá API trong bảng điều khiển API và dịch vụ > Thông tin xác thực trong bảng điều khiển Google Cloud.
Nếu bạn phát hiện thấy chúng không khớp, hãy lấy một tệp/đối tượng cấu hình Firebase mới, rồi thay thế tệp/đối tượng hiện có trong ứng dụng của bạn. Tệp/đối tượng cấu hình mới phải chứa một khoá API hợp lệ cho ứng dụng và dự án Firebase của bạn.
Lỗi 400: Service agents are being provisioned ... Service agents are needed to read the Cloud Storage file provided.
Nếu đang cố gắng gửi một yêu cầu đa phương thức bằng URL Cloud Storage for Firebase, bạn có thể gặp phải lỗi 400 sau đây:
Service agents are being provisioned ... Service agents are needed to read the Cloud Storage file provided.
Lỗi này là do một dự án không có các tác nhân dịch vụ bắt buộc được tự động cung cấp đúng cách khi API Vertex AI được bật trong dự án. Đây là một vấn đề đã biết đối với một số dự án và chúng tôi đang tìm cách khắc phục trên toàn cầu.
Sau đây là giải pháp tạm thời để khắc phục dự án của bạn và cung cấp chính xác các tác nhân dịch vụ này để bạn có thể bắt đầu đưa các URL Cloud Storage for Firebase vào các yêu cầu đa phương thức. Bạn phải là Chủ sở hữu của dự án và chỉ cần hoàn tất bộ nhiệm vụ này một lần cho dự án của mình.
Truy cập và xác thực bằng gcloud CLI.
Cách dễ nhất để làm việc này là thông qua Cloud Shell. Tìm hiểu thêm trong tài liệu về Google Cloud.Nếu được nhắc, hãy làm theo hướng dẫn xuất hiện trong thiết bị đầu cuối để chạy gcloud CLI đối với dự án Firebase của bạn.
Bạn sẽ cần mã dự án Firebase. Bạn có thể tìm thấy mã này ở đầu trang settings Cài đặt dự án trong bảng điều khiển Firebase.
Cung cấp các tác nhân dịch vụ cần thiết trong dự án của bạn bằng cách chạy lệnh sau:
curl -X POST -H "Authorization: Bearer $(gcloud auth print-access-token)" -H "Content-Type: application/json" https://us-central1-aiplatform.googleapis.com/v1/projects/PROJECT_ID/locations/us-central1/endpoints -d ''
Chờ vài phút để đảm bảo các tác nhân dịch vụ được cung cấp, sau đó thử lại việc gửi yêu cầu đa phương thức bao gồm URL Cloud Storage for Firebase.
Nếu bạn vẫn gặp lỗi này sau khi đợi vài phút, hãy liên hệ với Nhóm hỗ trợ Firebase.
Lỗi 403: Requests to this API firebasevertexai.googleapis.com ... are blocked.
Nếu bạn nhận được lỗi 403 có nội dung Requests to this API firebasevertexai.googleapis.com ... are blocked., thì điều này thường có nghĩa là khoá API trong cấu hình Firebase trong ứng dụng của bạn có các hạn chế ngăn khoá này gọi API bắt buộc.
Để khắc phục vấn đề này, bạn cần cập nhật các quy tắc hạn chế đối với khoá API trong bảng điều khiển Google Cloud để thêm API bắt buộc. Đối với Firebase AI Logic, bạn phải đảm bảo rằng API Firebase AI Logic (firebasevertexai.googleapis.com) có trong danh sách các API đã chọn có thể được gọi bằng khoá API.
Hãy làm theo các bước sau:
Trong bảng điều khiển Google Cloud, hãy mở bảng điều khiển API và Dịch vụ > Thông tin xác thực.
Chọn khoá API mà ứng dụng của bạn được định cấu hình để sử dụng (ví dụ: "khoá iOS" cho ứng dụng iOS).
Trên trang Chỉnh sửa khoá API, hãy tìm mục API restrictions (Hạn chế cho API).
Đảm bảo bạn đã chọn chế độ Hạn chế khoá. Nếu không, khoá của bạn sẽ không bị hạn chế và đây có thể không phải là nguyên nhân gây ra lỗi.
Trong trình đơn thả xuống Các API đã chọn, hãy tìm kiếm và chọn Firebase AI Logic API để thêm API đó vào danh sách các API đã chọn có thể được gọi bằng khoá API.
Nhấp vào Lưu.
Có thể mất tối đa 5 phút để các thay đổi có hiệu lực.
Lỗi 403: PERMISSION_DENIED: The caller does not have permission.
Nếu bạn nhận được lỗi 403 có nội dung PERMISSION_DENIED: The caller does not have permission., thì điều này thường có nghĩa là khoá API trong tệp/đối tượng cấu hình Firebase của bạn thuộc về một dự án Firebase khác.
Kiểm tra để đảm bảo khoá API có trong tệp/đối tượng cấu hình Firebase khớp với khoá API của ứng dụng. Bạn có thể xem tất cả khoá API trong bảng điều khiển API và dịch vụ > Thông tin xác thực trong bảng điều khiển Google Cloud.
Nếu bạn phát hiện thấy chúng không khớp, hãy lấy một tệp/đối tượng cấu hình Firebase mới, rồi thay thế tệp/đối tượng hiện có trong ứng dụng của bạn. Tệp/đối tượng cấu hình mới phải chứa một khoá API hợp lệ cho ứng dụng và dự án Firebase của bạn.
Lỗi 404: Firebase AI Logic genai config not found
Nếu bạn đang cố gắng sử dụng Gemini Developer API và nhận được lỗi 404 cho biết Firebase AI Logic genai config not found, thì điều này thường có nghĩa là dự án Firebase của bạn không có khoá API Gemini hợp lệ để sử dụng với các SDK Firebase AI Logic.
Sau đây là những nguyên nhân có thể gây ra lỗi này:
Bạn chưa thiết lập dự án Firebase cho Gemini Developer API.
Việc cần làm:
Trong bảng điều khiển Firebase, hãy chuyển đến Dịch vụ AI > Logic AI. Nhấp vào Bắt đầu, rồi chọn Gemini Developer API. Bật API và bảng điều khiển sẽ thiết lập dự án của bạn cho Gemini Developer API. Sau khi hoàn tất quy trình, hãy thử lại yêu cầu của bạn.Nếu bạn mới thực hiện quy trình thiết lập Firebase AI Logic trong bảng điều khiển Firebase, thì khoá API Gemini của bạn có thể chưa được cung cấp cho tất cả các dịch vụ phụ trợ bắt buộc ở mọi khu vực.
Việc cần làm:
Đợi vài phút rồi thử lại yêu cầu.Khoá API Gemini của bạn có thể đã bị xoá khỏi dự án Firebase.
Việc cần làm:
Tìm hiểu cách thay đổi khoá API Gemini mà Firebase AI Logic sử dụng.
Lỗi 404: mô hình "was not found or your project does not have access to it"?
Ví dụ: "Publisher Model projects/PROJECT-ID/locations/us-central1/publishers/google/models/gemini-3.1-pro-preview was not found or your project does not have access to it. Please ensure you are using a valid model version."
Có một số lý do khiến bạn có thể gặp phải lỗi như thế này.
Tên kiểu máy không hợp lệ
Nguyên nhân: Tên mẫu mà bạn cung cấp không phải là tên mẫu hợp lệ.
Khắc phục: Kiểm tra tên mẫu và phiên bản mẫu của bạn dựa trên danh sách tất cả các mẫu được hỗ trợ và có sẵn. Hãy nhớ kiểm tra các phân đoạn và thứ tự của chúng trong tên mô hình. Ví dụ:
- Tên mô hình Gemini 3.x Pro mới nhất:
gemini-3.1-pro-preview(chỉ có trong bản xem trước) - Tên mẫu Gemini 3.x Flash mới nhất:
gemini-3.5-flash - Tên mẫu Gemini 3.x Flash‑Lite mới nhất:
gemini-3.1-flash-lite - Tên mô hình Gemini 3.x Pro Image mới nhất (còn gọi là "Nano Banana Pro"):
gemini-3-pro-image - Tên mô hình mới nhất Gemini 3.x Flash Image (còn gọi là "Nano Banana 2"):
gemini-3.1-flash-image - Tên mô hình Gemini 2.5 Flash Image mới nhất (còn gọi là "Nano Banana"):
gemini-2.5-flash-image
- Tên mô hình Gemini 3.x Pro mới nhất:
Vị trí không hợp lệ (chỉ áp dụng nếu bạn sử dụng nhà cung cấp Vertex AI Gemini API)
Nguyên nhân: Mỗi yêu cầu sử dụng Vertex AI Gemini API phải bao gồm vị trí để truy cập vào mô hình. Yêu cầu của bạn có thể đang cố gắng truy cập vào một mô hình ở vị trí mà mô hình đó không có sẵn.
Khắc phục: Đảm bảo rằng yêu cầu của bạn đang cố gắng truy cập vào mô hình có sẵn.
Khi sử dụng Vertex AI Gemini API, Firebase AI Logic mặc định là
us-central1. Tuy nhiên, không phải mẫu nào cũng được hỗ trợ trongus-central1. Điều này có nghĩa là tuỳ thuộc vào mô hình, bạn có thể cần phải thiết lập rõ ràng một vị trí cụ thể trong quá trình khởi tạo.Gemini Dùng thử và thử nghiệm các mô hình: Bạn phải đặt vị trí thành
global(ngoại trừ các mô hình Live API). Tất cả các mô hình xem trước và thử nghiệm Gemini (ngoại trừ các mô hình Live API) chỉ có ở vị tríglobal.Các mô hình Gemini 3.x: Bạn phải đặt vị trí thành
globalkhi sử dụng Firebase AI Logic. Firebase AI Logic chưa hỗ trợ các vị tríusvàeu.Gemini 2.5 models: Bạn không bắt buộc phải thiết lập vị trí. Nếu bạn không chỉ định vị trí, giá trị mặc định sẽ là
us-central1.Gemini Live API models: Bạn không bắt buộc phải thiết lập vị trí. Nếu bạn không chỉ định vị trí, giá trị mặc định sẽ là
us-central1. Xin lưu ý rằng vị tríglobalkhông được hỗ trợ.
Tìm hiểu thêm về cách chỉ định vị trí để truy cập vào mô hình (bao gồm cả đoạn mã).
Lỗi 429: "You exceeded your current quota, please check your plan and billing details" hoặc "Resource exhausted, please try again later."
Lỗi 429 cho biết bạn đang vượt quá hạn mức hoặc mô hình mà bạn đang truy cập bị quá tải do các yêu cầu từ những người khác.
Hành động cần thực hiện phụ thuộc vào việc bạn đang sử dụng Gemini Developer API hay Vertex AI Gemini API. Để biết thêm thông tin về hạn mức và cách yêu cầu hạn mức bổ sung, hãy xem phần Hạn mức và giới hạn tốc độ.
Nếu bạn đang sử dụng Vertex AI Gemini API, thì tài liệu Google Cloud sẽ cung cấp thêm một số thông tin và hướng dẫn về Mã lỗi 429.