Trang này hướng dẫn cách khắc phục sự cố các mã lỗi thường gặp đối với 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 cho biết API key not valid. Please pass a valid API key., 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 không tồn tại hoặc chưa được thiết lập để sử dụng với ứng dụng và/hoặc dự án Firebase của bạn.
Kiểm tra để đảm bảo khoá API trong tệp cấu hình/đối tượng cấu hình Firebase khớp với khoá API cho ứng dụng của bạn. 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 các giá trị này 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 trong ứng dụng của bạn. Tệp/đối tượng cấu hình mới phải chứa 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 yêu cầu đa thức bằng URL Cloud Storage for Firebase, bạn có thể gặp lỗi 400 sau:
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 cấp phép tự động đúng cách khi API Agent Platform đượ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 nỗ lực khắc phục trên toàn hệ thống.
Sau đây là giải pháp khắc phục vấn đề cho dự án của bạn và cấp phép chính xác cho các tác nhân dịch vụ này để bạn có thể bắt đầu đưa 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 nhóm việc cần làm 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 để thực hiện việc này là từ 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 hiển thị trong dòng lệnh để chạy gcloud CLI trên 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 phần 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 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 ''
Hãy đợi vài phút để đảm bảo rằng các tác nhân dịch vụ đã được cấp phép, sau đó thử gửi lại yêu cầu đa phương thức có chứa URL Cloud Storage for Firebase.
Nếu bạn vẫn gặp lỗi này sau khi chờ vài phút, hãy liên hệ với Nhóm hỗ trợ Firebase.
Lỗi 403: PERMISSION_DENIED: To access this model, you must enforce Firebase App Check. Learn more: https://firebase.google.com/docs/ai-logic/app-check
Nếu bạn nhận được lỗi 403 - PERMISSION_DENIED cho biết To access this model, you must enforce Firebase App Check. Learn more: https://firebase.google.com/docs/ai-logic/app-check, thì tức là yêu cầu của bạn không có mã thông báo App Check hợp lệ và bạn đang cố gắng truy cập vào một mô hình thường bị sai mục đích.
Một số mô hình tạo sinh đã được xác định là thường bị các đối tượng xấu lợi dụng.
Vì bạn không thực thi App Check cho Firebase AI Logic, nên dự án của bạn dễ bị lợi dụng các mô hình này. Để giúp bảo vệ nhà phát triển, Firebase sẽ chặn quyền truy cập vào các mô hình này, trừ phi yêu cầu có chứa mã thông báo App Check hợp lệ (tức là App Check được thực thi cho Firebase AI Logic).
Nếu bạn muốn truy cập vào mô hình đã trả về lỗi, hãy làm như sau:
Thiết lập App Check cho Firebase AI Logic. Để phát triển cục bộ, hãy nhớ thiết lập App Check nhà cung cấp dịch vụ gỡ lỗi.
Việc thực thi App Check là rất quan trọng để giúp bảo vệ các mô hình Gemini API và Gemini khỏi hành vi sai trái, đồng thời bạn phải thực thi chính sách này để khắc phục lỗi này.
Gửi lại yêu cầu từ ứng dụng của bạn đến Firebase AI Logic.
Yêu cầu này sẽ gửi kèm một mã thông báo App Check hợp lệ và bạn sẽ không còn gặp lỗi
403 - PERMISSION_DENIEDnày nữa.Trước khi phát hành ứng dụng cho người dùng cuối, bạn cần thiết lập một nhà cung cấp dịch vụ chứng thực chính thức (chẳng hạn như App Attest, Play Integrity hoặc reCAPTCHA Enterprise) để người dùng cuối có thể truy cập vào tính năng AI của bạn khi App Check được thực thi.
Lỗi 403: PERMISSION_DENIED: Firebase AI Logic has been deactivated in this project. To resume using Firebase AI Logic, you must enforce Firebase App Check. Learn more: https://firebase.google.com/docs/ai-logic/app-check
Nếu bạn nhận được lỗi 403 - PERMISSION_DENIED cho biết
Firebase AI Logic has been deactivated in this project. To resume using
Firebase AI Logic, you must enforce Firebase App Check. Learn more:
https://firebase.google.com/docs/ai-logic/app-check,
điều đó có nghĩa là dự án Firebase của bạn đã được xác định là không hoạt động và bạn
chưa thực thi App Check cho Firebase AI Logic.
"Dự án không hoạt động" là những dự án đã bật Firebase AI Logic nhưng không có hoạt động sử dụng Firebase AI Logic nào gần đây.
Vì bạn không thực thi App Check cho Firebase AI Logic, nên dự án của bạn dễ bị lợi dụng Gemini API. Để giúp bảo vệ dự án của bạn, Firebase đã huỷ kích hoạt việc sử dụng Firebase AI Logic cho đến khi bạn thực thi App Check cho Firebase AI Logic.
Khi bạn đã sẵn sàng bắt đầu sử dụng lại Firebase AI Logic, hãy làm như sau:
Thiết lập App Check cho Firebase AI Logic. Để phát triển cục bộ, hãy nhớ thiết lập App Check nhà cung cấp dịch vụ gỡ lỗi.
Việc thực thi App Check là rất quan trọng để giúp bảo vệ các mô hình Gemini API và Gemini khỏi hành vi sai trái, đồng thời bạn phải thực thi chính sách này để khắc phục lỗi này.
Gửi lại yêu cầu từ ứng dụng của bạn đến Firebase AI Logic.
Yêu cầu này sẽ gửi kèm một mã thông báo App Check hợp lệ và bạn sẽ không còn gặp lỗi
403 - PERMISSION_DENIEDnày nữa.Nếu bạn đã thực thi App Check mà vẫn gặp lỗi này, hãy kiểm tra xem tính năng bảo vệ chống phát lại đã được bật cho Firebase AI Logic hay chưa (bao gồm cả ở chế độ "Chỉ giám sát").
Khi tính năng chống tấn công phát lại được bật, chỉ mã thông báo có giới hạn sử dụng mới được tính là đã xác minh cho Firebase AI Logic; mã thông báo phiên thông thường không xoá được lỗi này. Bạn có thể bật mã thông báo có giới hạn sử dụng trong ứng dụng hoặc tắt tính năng bảo vệ chống tấn công lặp lại cho Firebase AI Logic, gửi lại yêu cầu và đợi khoảng một ngày trước khi bật lại tính năng bảo vệ chống tấn công lặp lại (hoạt động của dự án được đánh giá lại hằng ngày).
Trước khi phát hành ứng dụng cho người dùng cuối, bạn cần thiết lập một nhà cung cấp dịch vụ chứng thực chính thức (chẳng hạn như App Attest, Play Integrity hoặc reCAPTCHA Enterprise) để người dùng cuối có thể truy cập vào tính năng AI của bạn khi App Check được thực thi.
Lỗi 403: PERMISSION_DENIED: The caller does not have permission.
Nếu bạn nhận được lỗi 403 cho biết 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 trong tệp cấu hình/đối tượng cấu hình Firebase khớp với khoá API cho ứng dụng của bạn. 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 các giá trị này 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 trong ứng dụng của bạn. Tệp/đối tượng cấu hình mới phải chứa khoá API hợp lệ cho ứng dụng và dự án Firebase của bạn.
Lỗi 403: Requests to this API firebasevertexai.googleapis.com ... are blocked.
Nếu bạn nhận được lỗi 403 cho biết 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 quy định hạn chế khiến khoá này không thể 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 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 Hạn chế cho API.
Đảm bảo bạn đã chọn mục Giới hạn 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 Selected APIs (API đã chọn), hãy tì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 đến 5 phút thì các thay đổi mới có hiệu lực.
Lỗi 404: Firebase AI Logic genai config not found
Nếu bạn nhận được lỗi 404 cho biết Firebase AI Logic genai config not found, thì điều đó thường có nghĩa là một chế độ cài đặt cho Firebase AI Logic bị định cấu hình sai hoặc bị thiếu.
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 nhà cung cấp Gemini API.
Việc cần làm:
Trong bảng điều khiển Firebase, hãy chuyển đến phần Dịch vụ AI > Logic AI. Nhấp vào Bắt đầu, rồi chọn nhà cung cấp Gemini API mà bạn muốn. Bật API và Firebase sẽ thiết lập dự án của bạn cho nhà cung cấp đó. Sau khi hoàn tất quy trình, hãy thử gửi lại yêu cầu.Nếu bạn vừa 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ì cấu hình cho Firebase AI Logic có thể chưa được cung cấp cho tất cả các dịch vụ phụ trợ bắt buộc ở tất cả các khu vực áp dụng.
Việc nên làm:
Hãy đợi vài phút rồi thử gửi lại yêu cầu.
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 vài lý do khiến bạn có thể gặp lỗi như thế này.
Tên mô hình không hợp lệ
Nguyên nhân: Tên kiểu máy mà bạn cung cấp không phải là tên kiểu máy hợp lệ.
Cách khắc phục: Kiểm tra tên và phiên bản mô hình của bạn trong danh sách tất cả mô hình đượ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ẫu. Ví dụ:
- Tên mô hình Gemini 4 Argon mới nhất:
gemini-4-argon - Tên mô hình Gemini 3.x Flash mới nhất:
gemini-3.8-flash - Tên mô hình Gemini 3.x Flash‑Lite mới nhất:
gemini-3.5-flash-lite - Tên mô hình Gemini Nano Banana 2.1 mới nhất:
gemini-nano-banana-2.1 - Tên mô hình Gemini Nano Banana 2 mới nhất:
gemini-3.1-flash-image - Tên mô hình Gemini Nano Banana 2 Lite mới nhất:
gemini-3.1-flash-lite-image - Tên mô hình Gemini Nano Banana Pro mới nhất:
gemini-3-pro-image
- Tên mô hình Gemini 4 Argon mới nhất:
Mô hình ngừng hoạt động (ngừng cung cấp)
Nguyên nhân: Mô hình mà bạn đang cố gắng truy cập đã qua ngày ngừng hoạt động (ngừng cung cấp) và đã bị vô hiệu hoá vĩnh viễn (ví dụ: các mô hình Gemini 2.5 sử dụng chung trên Agent Platform Gemini API (formerly Vertex AI), các mô hình Gemini 2.0 hoặc các mô hình Imagen).
Cách khắc phục: Hãy xem phần Câu hỏi thường gặp về các mô hình không còn được dùng nữa và đã ngừng hoạt động rồi cập nhật mã để sử dụng một mô hình thay thế đang hoạt động.
Vị trí không hợp lệ (chỉ áp dụng nếu sử dụng nhà cung cấp Agent Platform Gemini API (formerly Vertex AI))
Nguyên nhân: Yêu cầu của bạn có thể đang cố gắng truy cập vào một mô hình ở một vị trí không có mô hình đó.
Cách khắc phục: Đảm bảo yêu cầu của bạn đang cố gắng truy cập vào mô hình ở nơi mô hình đó được cung cấp.
Khi sử dụng Agent Platform Gemini API (formerly Vertex AI), bạn có thể tuỳ ý chỉ định một vị trí để truy cập vào mô hình trong quá trình khởi chạy. Nếu bạn không chỉ định vị trí, thì Firebase AI Logic sẽ mặc định là các vị trí sau:
- Khi sử dụng cú pháp khởi chạy "Nền tảng tác nhân":
global - Khi sử dụng cú pháp khởi chạy "Vertex AI" cũ:
us-central1
Tuy nhiên, không phải mô hình nào cũng được hỗ trợ ở những vị trí mặc định này. Điều này có nghĩa là, tuỳ thuộc vào mô hình, bạn có thể phải đặt một vị trí cụ thể một cách rõ ràng trong quá trình khởi chạy.
Các mô hình Gemini bản xem trước và thử nghiệm: Chỉ có ở vị trí
global.Mô hình ổn định Gemini 4.x và Gemini 3.x: Có ở vị trí
globalvà thường có ở vị tríusvàeu.Các mô hình Gemini Live API 2.5: Có ở nhiều địa điểm, nhưng không có ở
global. (Xin lưu ý rằng các mô hình Gemini 2.5 cho mục đích chung đã ngừng hoạt động đối với Agent Platform Gemini API (formerly Vertex AI).)
- Khi sử dụng cú pháp khởi chạy "Nền tảng tác nhân":
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."
Có một vài lý do khiến bạn có thể gặp lỗi như thế này.
Bạn đang vượt quá hạn mức hoặc mô hình bạn đang truy cập bị quá tải do 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 Agent Platform Gemini API (formerly Vertex AI). Để biết thêm thông tin về hạn mức và cách yêu cầu thêm hạn mức, hãy xem phần Giới hạn tốc độ và hạn mức.
Nếu bạn đang sử dụng Agent Platform Gemini API (formerly Vertex AI), thì tài liệu về Google Cloud sẽ cung cấp thêm một số bối cảnh và hướng dẫn về Mã lỗi 429.
Bạn đang cố gắng sử dụng một mô hình hoặc tính năng yêu cầu thanh toán, nhưng dự án Firebase của bạn đang sử dụng gói giá Spark.
Nếu đang dùng Gemini Developer API, bạn có thể có quyền truy cập có giới hạn vào một số mô hình và quyền truy cập vào nhiều tính năng cơ bản khi sử dụng "gói miễn phí" của Gemini Developer API. Cấp này cho phép bạn bắt đầu mà không cần cung cấp phương thức thanh toán, tức là bạn không cần nâng cấp dự án Firebase lên gói giá linh hoạt (trả tiền theo mức dùng).
Một số mô hình không có trong Gemini Developer API "bậc miễn phí" và yêu cầu "bậc có tính phí", tức là dự án của bạn phải sử dụng gói giá Blaze trả tiền theo mức dùng. Ví dụ: các mô hình sau đây hầu như luôn yêu cầu thông tin thanh toán:
- Hầu hết các mô hình bản xem trước và thử nghiệm
- Mô hình tạo nội dung nghe nhìn (như mô hình Gemini Nano Banana)
Một số mô hình cung cấp một số tính năng cơ bản trong Gemini Developer API "bậc miễn phí", nhưng sau đó yêu cầu "bậc trả phí" để sử dụng các tính năng nâng cao hơn. Ví dụ:
- Khi sử dụng hầu hết các mô hình Gemini 3.x,
bạn cần thanh toán để dùng tính năng Tạo sinh dựa trên dữ liệu thực tế bằng
Google Search hoặcGoogle Maps .
- Khi sử dụng hầu hết các mô hình Gemini 3.x,
bạn cần thanh toán để dùng tính năng Tạo sinh dựa trên dữ liệu thực tế bằng
Tìm hiểu về các gói giá của Firebase và Gemini Developer API.
Để biết thêm thông tin, hãy xem Gemini Developer API tài liệu về giá và Câu hỏi thường gặp về việc thanh toán.