Sửa lỗi API key

API key không hoạt động? Cách sửa lỗi 401, 402, 403, 429

Vì sao API key AI ngừng hoạt động: 401, 402, 403, 429 nghĩa là gì, mỗi nhà cung cấp báo hết số dư bằng mã nào, và cách sửa từng lỗi.

Cập nhật
  • Khi API key AI “không hoạt động”, mã lỗi cho biết lý do: 401 là bản thân key bị sai, 402 thường là số dư hoặc credit đã hết, 403 là key không được phép làm việc đó, còn 429 là quá nhiều yêu cầu, hoặc với một số nhà cung cấp là hết số dư.
  • Các nhà cung cấp không thống nhất mã báo hết số dư. DeepSeek, OpenRouter, Mistral, Together, Fireworks và hình thức trả trước của Gemini dùng 402; OpenAI, Kimi và Z.ai dùng 429; Qwen của Alibaba Cloud dùng 403. Hãy đọc nội dung thông báo, đừng chỉ nhìn con số.
  • Lỗi số dư không tự hết dù bạn chờ; lỗi giới hạn tốc độ thì thường hết. Bảng bên dưới liệt kê trang lỗi chính thức của từng nhà cung cấp, kiểm tra ngày 18 tháng 11 năm 2026.
Oriveo trên iPhone: màn hình nhà cung cấp, liệt kê những nhà cung cấp bạn đã kết nối và chi tiêu tháng này.

“API key không hoạt động” thực ra nghĩa là gì?

API key là mã bí mật mà app gửi kèm mỗi yêu cầu để nhà cung cấp AI biết đó là bạn và tính tiền vào tài khoản nào. Khi có trục trặc, nhà cung cấp trả về một lỗi: một con số ba chữ số gọi là mã trạng thái HTTP, kèm một thông báo ngắn.

Con số cho biết đây là loại vấn đề gì; thông báo cho biết chi tiết. Oriveo đổi các lỗi phổ biến thành tiêu đề dễ hiểu như “Khóa API không hợp lệ” hay “Đã hết hạn mức của nhà cung cấp”, được giải thích ở phần dưới trang này.

Tra nhanh: 401, 402, 403, 429 và 5xx

Bắt đầu từ đây. Tìm mã lỗi của bạn, rồi đọc phần tương ứng bên dưới. Bảng tóm tắt này dựa trên trang lỗi của OpenAI, Anthropic và các nhà cung cấp khác, tính đến ngày 18 tháng 11 năm 2026.

Tra nhanh: 401, 402, 403, 429 và 5xx
MãThường có nghĩa làChờ có tự hết không?Cần làm gì
401Key bị sai: thiếu ký tự, thừa khoảng trắng, key đã bị xóa, hoặc là key của nhà cung cấp hay khu vực khácKhôngSao chép lại key hoặc tạo key mới; kiểm tra nhà cung cấp và khu vực
402Cần thanh toán: số dư hoặc credit trả trước đã hết, hoặc có vấn đề về thanh toánKhôngNạp tiền, hoặc sửa phương thức thanh toán ở trang thanh toán của nhà cung cấp
403Key dùng được nhưng không được phép: quốc gia hoặc khu vực không được hỗ trợ, không có quyền dùng mô hình đó, hoặc cần một bước xác minhKhôngKiểm tra các khu vực được hỗ trợ, quyền của key và các bước xác minh
404Tên mô hình hoặc địa chỉ bị saiKhôngChọn mô hình khác hoặc kiểm tra lại địa chỉ
429Quá nhiều yêu cầu trong thời gian ngắn, hoặc với một số nhà cung cấp là hết số dư hay chạm hạn mức chi tiêuThường có, nếu là giới hạn tốc độChờ rồi thử lại; nếu thông báo nhắc tới quota, balance, credit hay spend limit thì nạp tiền hoặc nâng hạn mức
500–504, 529Sự cố hoặc quá tải phía nhà cung cấpThường cóThử lại sau hoặc đổi mô hình

Vì sao báo không đủ số dư hoặc hết quota?

Hầu hết nhà cung cấp cần credit trả trước hoặc một phương thức thanh toán đang hoạt động thì API mới chạy, và mỗi nơi báo hết số dư theo cách riêng. Tạo key mới không sửa được những lỗi này; nạp thêm credit thì được.

Bảng dưới đây ghi mã lỗi mà từng nhà cung cấp trong số 15 nhà cung cấp có sẵn của Oriveo nêu trong tài liệu cho trường hợp bạn hết số dư hoặc credit. “Không nêu” nghĩa là tài liệu của nhà cung cấp, kiểm tra ngày 18 tháng 11 năm 2026, không đưa ra mã HTTP cho trường hợp này.

Vì sao báo không đủ số dư hoặc hết quota?
Nhà cung cấpMã khi hết số dưNội dung thông báoTrang chính thức
OpenAI429credit_balance_exhausted (loại lỗi vẫn có thể ghi insufficient_quota)developers.openai.com/api/docs/guides/error-codes
Anthropic (Claude)Không nêu“Your credit balance is too low to access the Anthropic API”; lỗi thanh toán trả về 402 billing_errorplatform.claude.com/docs/en/api/errors (mã lỗi); platform.claude.com/docs/en/about-claude/api-credits-for-subscribers (thông báo)
Google Gemini402 (thanh toán trả trước)payment_required; 403 cũng có thể là tài khoản Cloud Billing còn nợ chưa trảaistudio.google.com/docs/api-errors
OpenRouter402Your account or API key has insufficient credits (tài khoản hoặc API key không đủ credit)openrouter.ai/docs/api-reference/errors
DeepSeek402Insufficient Balanceapi-docs.deepseek.com/quick_start/error_codes
xAI (Grok)Không nêuYêu cầu bị từ chối khi credit trả trước đã hếtdocs.x.ai/console/billing
Mistral AI402Payment requireddocs.mistral.ai/resources/error-glossary
GroqKhông có trong tài liệuGroq tính tiền sau khi dùng; trang lỗi không liệt kê lỗi số dưconsole.groq.com/docs/errors
Together AI402Payment Requireddocs.together.ai/docs/error-codes
Fireworks AI402Payment Requireddocs.fireworks.ai/guides/inference-error-codes
MiniMaxKhông nêu (mã nghiệp vụ 1008)insufficient balanceplatform.minimax.io/docs/api-reference/errorcode
Z.ai (GLM)429 (mã 1113)Insufficient balance or no resource package. Please recharge.docs.z.ai/api-reference/api-code
Qwen (Alibaba Cloud)403Arrearage hoặc isv.OUT_OF_SERVICE (tài khoản đang nợ phí)alibabacloud.com/help/en/model-studio/error-code
Kimi (Moonshot AI)429exceeded_current_quota_errorplatform.kimi.ai/docs/api/errors
SiliconFlowKhông có trong tài liệuKhông liệt kê lỗi số dưdocs.siliconflow.com/en/faqs/error-code

401: API key không hợp lệ hoặc xác thực thất bại

Lỗi 401 nghĩa là nhà cung cấp không nhận ra key. Các thông báo hay gặp là “Incorrect API key provided” (OpenAI), “authentication_error” (Anthropic), “Authentication Fails” (DeepSeek) và “Invalid API key: this is not an OpenRouter API key” (OpenRouter).

  • Sao chép lại key từ trang của nhà cung cấp, kiểm tra xem có thiếu ký tự hay dính khoảng trắng ở đầu hoặc cuối không.
  • Đảm bảo key thuộc đúng nhà cung cấp bạn đã chọn. Key OpenAI không dùng làm key OpenRouter được, và ngược lại.
  • Kimi, MiniMax và Qwen có các nền tảng riêng theo khu vực, và key của nền tảng này không dùng được ở nền tảng khác. Trong Oriveo, hãy chọn đúng khu vực ở mục “Điểm cuối chính thức” (trên iPhone là “URL yêu cầu chính thức”).
  • Nếu key đã bị xóa, bị thu hồi hoặc đã hết hạn, hãy tạo key mới.

402: cần thanh toán hoặc không đủ số dư

Lỗi 402 là chuyện tiền: số dư trả trước đã hết, hoặc phương thức thanh toán bị lỗi. Hãy nạp tiền hoặc cập nhật thông tin thanh toán ở trang thanh toán của nhà cung cấp, rồi gửi lại. Chờ đợi không giúp được gì.

Trong Oriveo, lỗi này hiện thành “Đã hết hạn mức của nhà cung cấp”: “Nhà cung cấp báo rằng hạn mức hoặc tín dụng của khóa API này đã hết. Hãy kiểm tra thanh toán tại nhà cung cấp, hoặc đổi mô hình.”

403: bị cấm hoặc bị từ chối quyền truy cập

Lỗi 403 nghĩa là nhà cung cấp nhận ra key nhưng không cho phép yêu cầu này. Lý do tùy từng nhà cung cấp:

  • OpenAI trả về “Country, region, or territory not supported” khi API được dùng từ một quốc gia mà OpenAI không hỗ trợ. Mỗi nhà cung cấp đều công bố danh sách quốc gia được hỗ trợ của mình.
  • Gemini trả về 403 khi một project ở gói miễn phí cần xác minh (FREE_TIER_VERIFICATION_REQUIRED), khi tài khoản Cloud Billing liên kết còn nợ chưa trả, hoặc khi Google đã chặn một key bị báo là đã lộ.
  • Anthropic trả về permission_error khi key không được dùng tài nguyên đó; hãy kiểm tra cài đặt tổ chức (organization) và workspace của bạn.
  • OpenRouter trả về 403 khi yêu cầu bị chặn do quyền truy cập, kiểm duyệt nội dung, guardrail hoặc giới hạn ngân sách.
  • SiliconFlow yêu cầu xác minh danh tính với một số mô hình.
  • Qwen dùng 403 cho tài khoản đang nợ phí, và cho AllocationQuota.FreeTierOnly khi hạn mức miễn phí đã hết mà cài đặt “Free Quota Only” đang bật.

429: quá nhiều yêu cầu, giới hạn tốc độ hoặc vượt quota

Phần lớn trường hợp, 429 nghĩa là bạn đã gửi quá nhiều yêu cầu hoặc quá nhiều token trong thời gian ngắn. Đó là giới hạn tốc độ (rate limit), và sẽ hết nếu bạn chờ vài chục giây. Nếu phản hồi có kèm thời gian Retry-After, hãy chờ đúng chừng đó.

Một số nhà cung cấp còn dùng 429 cho trường hợp hết số dư hoặc chạm hạn mức chi tiêu, và chờ đợi không sửa được: OpenAI (credit_balance_exhausted, hoặc hạn mức chi tiêu do bạn tự đặt), Kimi (exceeded_current_quota_error), Z.ai (mã 1113), và Anthropic khi một tổ chức chạm hạn mức chi tiêu hằng tháng (enforced_spend_limit_reached), kéo dài đến tháng sau trừ khi bạn xin lên mức sử dụng cao hơn.

Gói miễn phí giới hạn chặt hơn. Gói miễn phí của Gemini và các mô hình miễn phí của OpenRouter có giới hạn theo phút và theo ngày.

Trong Oriveo, giới hạn tốc độ hiện thành “Tỷ lệ giới hạn” trên web hoặc “Tỷ lệ nhà cung cấp có giới hạn” trên iPhone và Android. Nếu thông báo nhắc tới quota hoặc credit, Oriveo sẽ hiện “Đã hết hạn mức của nhà cung cấp” thay vào đó.

Các thông báo lỗi của Oriveo nghĩa là gì?

Đây là các thông báo bạn có thể gặp trong Oriveo, ghi nguyên văn theo giao diện tiếng Việt của app:

Các thông báo lỗi của Oriveo nghĩa là gì?
Oriveo hiển thịNghĩa là gìCần làm gì
Đã lưu, nhưng khóa có vẻ không hợp lệ. Bạn có thể xác minh lại sau trong cài đặt nhà cung cấp.Oriveo đã lưu nhà cung cấp, nhưng nhà cung cấp từ chối key trong lúc kiểm traSao chép lại key và cập nhật trong cài đặt của nhà cung cấp đó
Khóa API không hợp lệNhà cung cấp trả về 401 hoặc 403Kiểm tra hoặc thay key; với 403, kiểm tra khu vực và quyền
Đã hết hạn mức của nhà cung cấpNhà cung cấp cho biết credit hoặc quota của key này đã hết (402, hoặc 429 có nhắc tới quota)Nạp tiền ở nhà cung cấp, hoặc đổi sang mô hình khác
Tỷ lệ giới hạn (web) / Tỷ lệ nhà cung cấp có giới hạn (iPhone, Android)Hiện đang có quá nhiều yêu cầu (429)Chờ một chút rồi thử lại
Đã dùng hết hạn mức miễn phí (web, iPhone) / Đã đạt hạn mức Free (Android)Hạn mức Oriveo Free hôm nay đã hết; việc này không liên quan đến key của bạnThêm API key của riêng bạn, hoặc chờ hạn mức đặt lại lúc 00:00 UTC
Màn hình Nhà cung cấp của Oriveo liệt kê các nhà cung cấp đã kết nối như OpenAI, Z.ai, Groq, Gemini và Anthropic, mỗi nhà cung cấp kèm chi tiêu
Mở một nhà cung cấp trong danh sách này để kiểm tra hoặc thay key.

Đang dùng endpoint tùy chỉnh, relay hay gateway?

Nếu bạn kết nối qua một endpoint tùy chỉnh, lỗi có thể đến từ chính dịch vụ đó hoặc từ nhà cung cấp phía sau nó. Khi Oriveo báo “Kết nối này không liên lạc được với nhà cung cấp thượng nguồn”, tài khoản của chính dịch vụ đó với nhà cung cấp có thể không hợp lệ, hết credit hoặc đang bị giới hạn tốc độ. Đó không phải lỗi cấu hình của bạn; hãy chuyển sang kết nối khác hoặc liên hệ bên vận hành dịch vụ.

Kiểm tra những điều này trước khi tạo key mới

Key mới chỉ sửa được lỗi 401, gần như không sửa được gì khác. Hãy rà danh sách này trước:

  • Bạn đã chọn đúng nhà cung cấp, và với Kimi, MiniMax, Qwen, SiliconFlow và Z.ai thì đúng cả khu vực.
  • Bạn đã sao chép đủ cả key, không dính khoảng trắng.
  • Tài khoản còn credit, hoặc có phương thức thanh toán đang hoạt động.
  • Quốc gia hoặc khu vực của bạn có trong danh sách được nhà cung cấp hỗ trợ.
  • Mô hình bạn chọn có sẵn cho tài khoản hoặc mức sử dụng (tier) của bạn.

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

Vì sao API key của tôi không hoạt động?
Hãy xem mã lỗi. 401 là key sai, 402 là số dư hoặc credit đã hết, 403 là yêu cầu không được phép (thường do khu vực hoặc quyền), còn 429 là quá nhiều yêu cầu, hoặc với một số nhà cung cấp là hết số dư.
Lỗi 401 với API key nghĩa là gì?
Nhà cung cấp không nhận ra key. Hãy sao chép lại, không dính khoảng trắng, kiểm tra key có đúng nhà cung cấp và khu vực bạn chọn không, hoặc tạo key mới.
Lỗi 402 Payment Required là gì?
Số dư hoặc credit trả trước của bạn đã hết, hoặc có vấn đề về thanh toán. DeepSeek, OpenRouter, Mistral, Together, Fireworks và hình thức trả trước của Gemini dùng mã này. Hãy nạp tiền ở trang thanh toán của nhà cung cấp; chờ đợi không sửa được.
Lỗi 429 là do giới hạn tốc độ hay do hết quota?
Có thể là cả hai. Thường đó là giới hạn tốc độ, chờ một lát sẽ hết. Nhưng OpenAI, Kimi và Z.ai cũng trả về 429 khi số dư của bạn đã hết, nên nếu thông báo nhắc tới quota, balance hay credit thì hãy nạp thêm credit thay vì chờ.
Vì sao OpenAI API key báo insufficient_quota?
Tài khoản OpenAI API của bạn đã hết credit trả trước. OpenAI trả về 429 với mã credit_balance_exhausted, và loại lỗi vẫn có thể ghi insufficient_quota. Hãy nạp credit trong phần cài đặt thanh toán của OpenAI; tạo key mới không giúp được.
Vì sao API key mới đã sao chép đúng mà vẫn không chạy?
Thường là vì tài khoản chưa có credit hoặc chưa thiết lập thanh toán, key thuộc khu vực khác, hoặc API không được cung cấp ở quốc gia của bạn. Hãy kiểm tra những điều đó trước khi tạo thêm key.

Bài liên quan

Từ blog

Thông báo lỗi dễ hiểu cho mọi key

Mở bản web hoặc tải Oriveo cho iPhone hay Android, thêm key của 15 nhà cung cấp và biết rõ lý do mỗi khi một yêu cầu thất bại.

Chưa có API key? Hãy bắt đầu với Oriveo Free.