Mã lỗi

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 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 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.

1. Truy cập và xác thực bằng gcloud CLI.
   Cách dễ nhất để làm việc này là từ Cloud Shell. Tìm hiểu thêm trong tài liệu về Google Cloud.

2. 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.

3. 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 ''
   

4. 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: 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ì có nghĩa 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ị sử dụng 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 có nguy cơ bị lạm 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ó mã thông báo App Check hợp lệ (nghĩa 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:

1. Thiết lập App Check cho Firebase AI Logic. Đối với quá trình phát triển cục bộ, hãy đảm bảo rằng bạn 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 để 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 để xoá lỗi này.

2. 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 theo 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_DENIED này nữa.

3. 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 trình cung cấp chứng thực sản xuất (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 không có App Check được thực thi 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 gần đây.

Vì bạn không bắt buộc phải dùng App Check cho Firebase AI Logic, nên dự án của bạn dễ bị lạm dụng Gemini API. Để giúp bảo vệ dự án của bạn, Firebase đã vô hiệu hoá 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:

1. Thiết lập App Check cho Firebase AI Logic. Đối với quá trình phát triển cục bộ, hãy đảm bảo rằng bạn 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 để 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 để xoá lỗi này.

2. 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 theo 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_DENIED này nữa.

3. 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 trình cung cấp chứng thực sản xuất (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 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 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:

1. 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.

2. 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).

3. Trên trang Chỉnh sửa khoá API, hãy tìm mục API restrictions (Hạn chế cho API).

4. Đả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.

5. 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.

6. 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 404: Firebase AI Logic genai config not found

Nếu bạn nhận được lỗi 404 có nội dung Firebase AI Logic genai config not found, thì điều đó thường có nghĩa là 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 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ử 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ì 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 cần làm:
  Đợi vài phút rồi thử 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 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 và phiên bản mô hình của bạn dựa trên danh sách tất cả cá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ô 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ô 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 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 Gemini 3.x Flash Image mới nhất (còn gọi là "Nano Banana 2"): gemini-3.1-flash-image
    • Gemini 3.x Flash‑Lite Image Mới nhất (còn gọi là "Nano Banana 2 Lite") Tên mô hình: gemini-3.1-flash-lite-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

• Vị trí không hợp lệ (chỉ áp dụng nếu bạn 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 ở 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 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 tạo. 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 "Agent Platform": global
    • Khi sử dụng cú pháp khởi tạo "Vertex AI" cũ: us-central1

    Tuy nhiên, không phải mẫu 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 thiết lập rõ ràng một vị trí cụ thể trong quá trình khởi tạo.

    • Gemini preview và experimental models (mô hình thử nghiệm và mô hình xem trước): Chỉ có ở vị trí global.

    • Gemini 3.x Các mô hình ổn định: Có ở vị trí global và thường có ở vị trí us và eu.

    • Các mẫu Gemini 2.5: Có ở nhiều địa điểm. Xin lưu ý rằng các mô hình Gemini Live API 2.5 không có trong global.

  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 số lý do khiến bạn có thể gặp phải lỗi như thế này.

• 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 của người khác.

  Hành động cần thực hiện sẽ tuỳ 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 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 Agent Platform Gemini API (formerly Vertex AI), thì tài liệu Google Cloud cung cấp thêm một số thông tin 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 tính phí, nhưng dự án Firebase của bạn đang sử dụng gói giá Spark.

  Nếu đang sử 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 trong "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 trả 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 tính phí:

    • Hầu hết các mô hình xem trước và thử nghiệm
    • Các mô hình tạo hình ảnh ("các mô hình Nano Banana")

  • Một số mô hình cung cấp một số tính năng cơ bản trong "gói miễn phí" Gemini Developer API, nhưng sau đó yêu cầu "gói 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 phải thanh toán để sử dụng tính năng Nền tảng với Google Search hoặc Google Maps.

  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.