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

“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.
| Mã | Thường có nghĩa là | Chờ có tự hết không? | Cần làm gì |
|---|---|---|---|
| 401 | Key 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ác | Không | Sao chép lại key hoặc tạo key mới; kiểm tra nhà cung cấp và khu vực |
| 402 | Cần thanh toán: số dư hoặc credit trả trước đã hết, hoặc có vấn đề về thanh toán | Không | Nạp tiền, hoặc sửa phương thức thanh toán ở trang thanh toán của nhà cung cấp |
| 403 | Key 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 minh | Không | Kiểm tra các khu vực được hỗ trợ, quyền của key và các bước xác minh |
| 404 | Tên mô hình hoặc địa chỉ bị sai | Không | Chọn mô hình khác hoặc kiểm tra lại địa chỉ |
| 429 | Quá 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êu | Thườ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, 529 | Sự cố hoặc quá tải phía nhà cung cấp | Thườ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.
| Nhà cung cấp | Mã khi hết số dư | Nội dung thông báo | Trang chính thức |
|---|---|---|---|
| OpenAI | 429 | credit_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_error | platform.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 Gemini | 402 (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 |
| OpenRouter | 402 | Your account or API key has insufficient credits (tài khoản hoặc API key không đủ credit) | openrouter.ai/docs/api-reference/errors |
| DeepSeek | 402 | Insufficient Balance | api-docs.deepseek.com/quick_start/error_codes |
| xAI (Grok) | Không nêu | Yêu cầu bị từ chối khi credit trả trước đã hết | docs.x.ai/console/billing |
| Mistral AI | 402 | Payment required | docs.mistral.ai/resources/error-glossary |
| Groq | Không có trong tài liệu | Groq 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 AI | 402 | Payment Required | docs.together.ai/docs/error-codes |
| Fireworks AI | 402 | Payment Required | docs.fireworks.ai/guides/inference-error-codes |
| MiniMax | Không nêu (mã nghiệp vụ 1008) | insufficient balance | platform.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) | 403 | Arrearage hoặc isv.OUT_OF_SERVICE (tài khoản đang nợ phí) | alibabacloud.com/help/en/model-studio/error-code |
| Kimi (Moonshot AI) | 429 | exceeded_current_quota_error | platform.kimi.ai/docs/api/errors |
| SiliconFlow | Không có trong tài liệu | Khô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:
| 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 tra | Sao 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 403 | Kiể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ấp | Nhà 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ạn | Thêm API key của riêng bạn, hoặc chờ hạn mức đặt lại lúc 00:00 UTC |

Đ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?
Lỗi 401 với API key nghĩa là gì?
Lỗi 402 Payment Required là gì?
Lỗi 429 là do giới hạn tốc độ hay do hết quota?
Vì sao OpenAI API key báo insufficient_quota?
Vì sao API key mới đã sao chép đúng mà vẫn không chạy?
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.