Lỗi Kimi API: xử lý 401, 404, 429 và quá thời gian (2026)

Khi Kimi API báo lỗi, trước hết xem ba thứ: mã trạng thái HTTP, error.type và request_id. Cùng là 429, có thể do máy chủ quá tải, tổ chức bị giới hạn, cũng có thể do số dư không đủ; cùng là 401, có thể do Key viết sai, cũng có thể do dùng lẫn site Trung Quốc và site quốc tế. Phân loại trước, rồi mới sửa mã.

Bài viết chia thành bốn loại 401, 404, 429 và quá thời gian, nêu nguyên nhân, các bước điều tra và mã lùi có thể dùng lại. Mô hình và giá căn cứ theo bảng giá mô hình trên site.

Lưu ý: Moonshot và Kimi là nhãn hiệu của chủ sở hữu tương ứng. Loại lỗi, quy tắc giới hạn tốc độ và hành vi giao diện có thể điều chỉnh; bài viết lấy tình hình phổ biến tháng 10 năm 2026 làm ví dụ, cuối cùng căn cứ theo tài liệu chính thức.

1. Tra nhanh mã trạng thái

Mã trạng thái	Loại lỗi	Ý nghĩa thường gặp	Hướng xử lý
400	`invalid_request_error`	Tham số sai, ngữ cảnh quá dài, vượt giới hạn đầu ra	Sửa yêu cầu
400	`content_filter`	Đầu vào hoặc đầu ra chạm an toàn nội dung	Điều chỉnh prompt
401	`invalid_authentication_error`	Key không hợp lệ, không khớp khu vực	Sửa thông tin xác thực
401	`incorrect_api_key_error`	Thiếu hoặc sai Key	Sửa thông tin xác thực
403	`permission_denied_error`	Giao diện chưa mở, danh sách IP, số dư hoặc quyền	Kiểm tra quyền và số dư
404	`resource_not_found_error`	Tên mô hình hoặc đường dẫn sai	Xem danh sách mô hình
429	`engine_overloaded_error`	Máy chủ quá tải	Lùi và thử lại
429	`rate_limit_reached_error`	Vượt đồng thời, RPM, TPM hoặc TPD	Giảm tốc hoặc tăng hạn mức
429	`exceeded_current_quota_error`	Nợ phí, số dư không đủ, phiếu hết hiệu lực	Nạp tiền
499	`client_closed_request`	Máy khách hoặc proxy ngắt sớm	Kiểm tra thời gian chờ và truyền phát
500	`server_error`	Lỗi nội bộ máy chủ	Lùi và thử lại
503	`server_unavailable`	Dịch vụ tạm không khả dụng	Lùi và thử lại
504	`Gateway Time-out`	Yêu cầu dài chờ quá lâu	Chuyển sang truyền phát

Số dư không đủ ở các điểm vào khác nhau có thể biểu hiện là 403 hoặc 429; không thể chỉ dựa vào mã trạng thái, phải lấy error.type làm chuẩn. Nhật ký tối thiểu ghi thời gian, mã trạng thái, loại lỗi, tên mô hình và request_id; không ghi toàn bộ Key và nội dung nhạy cảm.

2. 401: kiểm tra khu vực trước, rồi kiểm tra Key

Key site Trung Quốc có đang cấu hình địa chỉ site quốc tế không, hoặc ngược lại. Tài khoản, số dư, Key của hai site hoàn toàn độc lập.
Có dùng lẫn Key của các dòng sản phẩm khác nhau không, ví dụ nền tảng mở, Kimi Code và hội viên.
Key có khoảng trắng, xuống dòng hoặc dấu ngoặc thừa ở đầu cuối không.
Biến môi trường có thực sự được nạp không; có thể chỉ in phần đầu để xác nhận.
Key có bị xóa, luân chuyển hoặc không có quyền với dự án hiện tại không.
Header có phải Authorization: Bearer <key> không, đường dẫn có phải /v1/chat/completions không.

export MOONSHOT_API_KEY="khóa-của-bạn"

curl "https://api.moonshot.cn/v1/chat/completions" \
  -H "Authorization: Bearer $MOONSHOT_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "kimi-k2.6",
    "max_completion_tokens": 64,
    "messages": [{"role": "user", "content": "Chỉ trả lời OK"}]
  }'

Lệnh này trả 200 nghĩa là Key, khu vực và tên mô hình đều thông. Nếu vẫn báo 401, đổi sang một Key đã biết dùng được để kiểm tra, phân biệt vấn đề ở bản thân Key hay cấu hình cổng.

3. 404: tên mô hình và base_url hay sai nhất

404 không nhất thiết là mô hình ngừng cung cấp; có bốn nguyên nhân phổ biến:

Dùng OpenAI SDK nhưng không đặt base_url, yêu cầu gửi đến địa chỉ OpenAI mặc định và trả mô hình không tồn tại.
Tên mô hình viết sai, hoặc dùng phiên bản tài khoản hiện tại không có quyền truy cập.
Đường dẫn thừa hoặc thiếu /v1, hoặc viết giao diện trò chuyện thành đường dẫn khác.
Tên mô hình và quyền của site Trung Quốc và site quốc tế khác nhau.

Trước hết dùng cùng một Key lấy danh sách mô hình, xác nhận tài khoản thấy được gì:

curl "https://api.moonshot.cn/v1/models" \
  -H "Authorization: Bearer $MOONSHOT_API_KEY"

Mô hình không có trong danh sách thì đừng đoán. Mô hình có khả dụng hay không căn cứ theo phản hồi thực tế của tài khoản và bảng giá mô hình trên site. Nếu danh sách mô hình trả về được nhưng giao diện trò chuyện vẫn 404, kiểm tra đường dẫn có thiếu /v1 không, và máy khách có ghép trùng base_url với đường dẫn đầy đủ không.

4. 429: ba loại, cách xử lý khác nhau

`error.type`	Ý nghĩa	Có thử lại không	Xử lý
`engine_overloaded_error`	Máy chủ quá tải	Có	Lùi theo `Retry-After`, giảm đồng thời
`rate_limit_reached_error`	Vượt đồng thời, RPM, TPM, TPD cấp tổ chức	Một phần	Giảm tốc, tách Key, nâng hạng
`exceeded_current_quota_error`	Nợ phí, số dư không đủ, phiếu hết hiệu lực	Không nên	Nạp tiền hoặc kiểm tra hóa đơn

Vượt TPD thường chỉ có thể đợi đến hôm sau hoặc nâng hạn mức; tiếp tục thử lại vô nghĩa. Yêu cầu bị 429 ngắt thường không bị tính phí, nhưng thử lại thành công sẽ tính phí bình thường; đừng vì sợ tốn tiền mà thử lại vô hạn, cũng đừng thấy 429 là cho rằng tài khoản đã bị trừ tiền. OpenAI SDK mặc định tự thử lại, có thể khuếch đại một lần 429 thành nhiều yêu cầu; môi trường sản xuất phải đặt max_retries rõ ràng và dùng logic lùi của riêng bạn.

import random
import time
from openai import OpenAI, RateLimitError

client = OpenAI(
    api_key="khóa-của-bạn",
    base_url="https://api.moonshot.cn/v1",
    max_retries=0,
)

def ask(prompt: str, retries: int = 4) -> str:
    for attempt in range(retries):
        try:
            resp = client.chat.completions.create(
                model="kimi-k2.6",
                messages=[{"role": "user", "content": prompt}],
                max_completion_tokens=1024,
            )
            return resp.choices[0].message.content
        except RateLimitError as exc:
            body = exc.body or {}
            etype = (body.get("error") or {}).get("type", "")
            if etype == "exceeded_current_quota_error":
                raise RuntimeError("Số dư hoặc hạn mức không đủ, hãy nạp tiền trước")
            wait = min(2 ** attempt, 20) + random.random()
            print(etype, "chờ", round(wait, 1), "giây")
            time.sleep(wait)
    raise RuntimeError("Đã dùng hết số lần thử lại")

Thử lại chỉ phù hợp với lỗi tạm thời. Với nghiệp vụ đã tạo tác dụng phụ, trước hết dùng khóa lũy đẳng hoặc kiểm tra trạng thái để xác nhận đã thực thi chưa, rồi mới quyết định có gửi lại.

5. Quá thời gian và 504

Tạo văn bản dài, phân tích tài liệu dài và Agent mã nguồn dễ gặp quá thời gian nhất. Thứ tự xử lý:

Đổi không truyền phát sang stream=True, để kết nối liên tục có dữ liệu trả về.
Đặt thời gian chờ kết nối và thời gian chờ đọc hợp lý, không dùng giá trị mặc định của SDK.
Kiểm tra proxy công ty, cổng và công cụ định tuyến cục bộ có ngắt kết nối sớm không; trường hợp này có thể biểu hiện là 499.
Dùng max_completion_tokens kiểm soát độ dài đầu ra mỗi lần, nhiệm vụ quá dài chia đoạn.
Ghi request ID và thời gian mỗi lần quá thời gian, phân biệt mô hình chậm, mạng chậm hay cổng chậm.

stream = client.chat.completions.create(
    model="kimi-k2.6",
    messages=[{"role": "user", "content": "Viết một danh sách kiểm tra triển khai"}],
    max_completion_tokens=2048,
    stream=True,
    stream_options={"include_usage": True},
)

for chunk in stream:
    if chunk.choices and chunk.choices[0].delta.content:
        print(chunk.choices[0].delta.content, end="")

Truyền phát không làm giảm đơn giá, nhưng giảm rõ rệt lãng phí “đợi đến quá thời gian rồi thử lại”. Thời gian chờ kết nối có thể đặt ngắn hơn; thời gian chờ đọc phải đặt theo thời gian tạo tối đa; tình huống truyền phát không nên dùng lại thời gian chờ đọc của không truyền phát, nếu không kết nối sẽ bị chính máy khách cắt khi đang tạo bình thường.

6. Bảng thứ tự điều tra

Ghi mã trạng thái, error.type, request_id, tên mô hình và thời điểm xảy ra.
401, 403 kiểm tra khu vực, Key, dòng sản phẩm, quyền và số dư.
404 kiểm tra base_url, tên mô hình và quyền tài khoản, xác minh bằng danh sách mô hình.
400 kiểm tra độ dài ngữ cảnh, giới hạn đầu ra, định dạng tệp và an toàn nội dung.
429 chia theo error.type thành quá tải, giới hạn tốc độ, nợ phí để xử lý.
499, 504 kiểm tra truyền phát, thời gian chờ, proxy và duy trì kết nối.
500, 503 lùi và thử lại; nếu liên tục xuất hiện thì gửi kèm request_id cho nhà cung cấp.
Sau mỗi sự cố bổ sung giám sát và cảnh báo, đừng đợi người dùng phản hồi mới phát hiện.

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

429 và 503 khác nhau thế nào?

429 có thể do máy chủ quá tải, cũng có thể do hạn mức hoặc số dư tài khoản; phải xem error.type trước. 503 nghĩa là dịch vụ tạm không khả dụng, thường lùi rồi thử lại. Điểm chung là đều không nên thử lại dồn dập với khoảng cách cố định.

Nạp tiền rồi vẫn 401 thì làm sao?

Trước hết xác nhận khoản nạp và Key thuộc cùng khu vực, cùng dòng sản phẩm. Đổi sang một Key mới tạo để kiểm tra, loại trừ khả năng Key cũ bị xóa hoặc biến môi trường bị lưu đệm.

Ngữ cảnh quá dài báo lỗi gì?

Thường là 400 invalid_request_error, thông báo lỗi có nhắc Token đầu vào quá dài. Rút ngắn đầu vào, cắt lịch sử hoặc đổi sang phiên bản có ngữ cảnh lớn hơn.

Có nên bật tự thử lại của SDK không?

Có thể bật, nhưng phải đặt giới hạn. Thử lại mặc định có thể khuếch đại 429; môi trường sản xuất nên tắt tự thử lại của SDK, tự làm lùi theo cấp số nhân và cảnh báo theo loại lỗi.

Phân biệt lỗi cổng và lỗi chính thức thế nào?

Dùng cùng một yêu cầu đánh vào trực tiếp và cổng, so mã trạng thái, error.type và request_id. Có thể nhanh chóng xác định là thượng nguồn, mạng, Key hay cấu hình cổng.

Bước tiếp theo

Trước hết tạo Key kiểm thử tại ZSQH AI Gateway, diễn tập lần lượt 401, 404, 429 và quá thời gian, rồi kết nối giám sát sản xuất. Mô hình khả dụng và giá căn cứ theo bảng giá mô hình.