Lỗi "không đủ token": nghĩa là gì và cách khắc phục

"Không đủ token" không phải là một lỗi duy nhất. Người ta dùng cụm từ này cho năm vấn đề khác nhau: số dư trống, yêu cầu gửi quá nhanh, khóa sai, prompt không vừa cửa sổ ngữ cảnh của model, hoặc câu trả lời chạm giới hạn đầu ra và dừng giữa câu. Mỗi vấn đề có cách khắc phục riêng, và cách nhanh nhất để phân biệt chúng là mã trạng thái HTTP và nội dung lỗi, không phải câu chữ của thông báo.

Tìm triệu chứng của bạn trong bảng, chạy kiểm tra, áp dụng cách khắc phục.

Ba nghĩa có thể của "token"#

Từ trong thông báo lỗi chỉ đến ba đại lượng khác nhau.

• Số dư. Token là thứ bạn trả tiền, nên "hết token" thường có nghĩa là "hết tiền". Trên dịch vụ trả trước, đó là số dư.
• Giới hạn mỗi phút. Giới hạn có thể tính theo yêu cầu hoặc theo token mỗi phút. Chạm một giới hạn thì cách khắc phục là chờ và gửi ít hơn mỗi lần.
• Kích thước cửa sổ. Cửa sổ ngữ cảnh là số token model có thể đọc trong một yêu cầu, gồm prompt của bạn và câu trả lời của nó.

Và một điều nó không bao giờ có nghĩa: API key không phải là kho token. Khóa định danh tài khoản của bạn. Thứ cạn kiệt là số dư phía sau nó, hoặc một giới hạn gắn với nó. Nếu bạn mới làm quen với đơn vị này, hãy bắt đầu với Token trong AI là gì?.

1. Số dư trống#

Tài liệu API của DeepSeek mô tả HTTP 402 Insufficient Balance là "Bạn đã hết số dư". API của Claude dùng 402 billing_error cho các vấn đề thanh toán và hóa đơn. Tên khác nhau, cùng một tình huống: tiền đã hết.

CheapTokens về nguyên tắc hoạt động tương tự: số dư trả trước, trả theo mức dùng, một số dư cho mọi model. Vậy khi có sự cố, hãy xem số dư trước. Đó là kiểm tra mười giây và loại trừ nguyên nhân phổ biến nhất.

2. Bạn chạm giới hạn tốc độ#

DeepSeek ghi HTTP 429 Rate Limit Reached là yêu cầu đến quá nhanh, hoặc vượt giới hạn đồng thời hay QPS. Cách khắc phục là điều tiết: ít yêu cầu song song hơn, và độ trễ thử lại tăng dần (1 s, 2 s, 4 s) thay vì dồn dập vào endpoint.

Một cái bẫy. API của Claude cũng trả 429 rate_limit_error khi bạn chạm hạn mức chi tiêu hàng tháng của gói, và phản hồi đó không có header retry-after. Vậy một 429 không bao giờ hết sau khi chờ có thể là về tiền, không phải tốc độ. Nếu chờ không giúp ích, quay lại nguyên nhân 1.

3. Khóa sai#

HTTP 401 là vấn đề khóa trong cả hai tài liệu: DeepSeek liệt kê là API key sai, Claude là authentication_error. Lý do thường gặp là dấu cách hoặc xuống dòng thừa bị sao chép cùng khóa, khóa đã bị xóa hoặc tạo lại, và khóa gửi đến sai địa chỉ. Khóa của một dịch vụ không hoạt động ở URL của dịch vụ khác. Với CheapTokens, base URL là https://api.cheaptokens.dev/v1.

Về các lỗi khác bạn có thể gặp khi kết nối, xem Các lỗi kết nối phổ biến và cách khắc phục.

4. Prompt không vừa cửa sổ ngữ cảnh#

Cửa sổ ngữ cảnh tính mọi thứ model đọc trong một yêu cầu: system prompt, toàn bộ lịch sử hội thoại, tin nhắn mới của bạn, và chỗ cho câu trả lời. Trên CheapTokens, cửa sổ của các model trong danh mục của chúng tôi là:

Một cuộc trò chuyện không có bộ nhớ riêng. Client gửi lại toàn bộ lịch sử với mỗi yêu cầu, nên mỗi yêu cầu lớn hơn yêu cầu trước. Đây là một cuộc trò chuyện giả định để minh họa sự tăng trưởng (số tròn, chỉ để minh họa): system prompt 1.000 token, và mỗi lượt thêm khoảng 500 token câu hỏi và 1.500 token câu trả lời, tổng cộng 2.000.

1.000 + 30 × 2.000 = 61.000 token

Đó là kích thước lịch sử sau 30 lượt. Mỗi token trong số đó lại được tính là đầu vào ở yêu cầu tiếp theo. Yêu cầu thứ 31 mang lịch sử 61.000 token đó cộng câu hỏi mới 500 token, nên đầu vào của nó là 61.500 token. Với câu trả lời 1.500 token trên MiniMax-M2.7, chi phí là $0.0033. Đây là cả ba model cho cùng yêu cầu, kèm giá OpenRouter để so sánh:

Cùng cuộc trò chuyện đó lấp đầy cửa sổ nhỏ nhất trong khoảng một trăm lượt:

(200.000 − 1.000) / 2.000 = 99,5

Khi tràn, nhà cung cấp từ chối yêu cầu. Mã trạng thái thay đổi theo nhà cung cấp, nên hãy đọc nội dung lỗi. Ví dụ, 413 request_too_large của Claude là về kích thước yêu cầu tính bằng byte (32 MB cho Messages), một giới hạn khác với cửa sổ token.

Cần làm gì:

• Bỏ các lượt cũ nhất, hoặc thay chúng bằng một bản tóm tắt ngắn.
• Đừng dán cả tài liệu khi tác vụ chỉ cần một chương.
• Chuyển sang model có cửa sổ lớn hơn nếu bạn thực sự cần toàn bộ văn bản.

5. Câu trả lời bị cắt#

Không có lỗi ở đây, và đó là điều khiến trường hợp này khó hiểu. Model chỉ đơn giản dừng vì chạm max_tokens hoặc giới hạn đầu ra của chính model. Trong định dạng Chat Completions, dấu hiệu là finish_reason: "length" trên choice.

Trên CheapTokens, DeepSeek-V4-Flash có thể trả tối đa 32.768 token mỗi câu trả lời; GLM-5.3-Flash và MiniMax-M2.7 tối đa 8.192. Nếu max_tokens của bạn thấp hơn mức đó, hãy tăng lên. Nếu bạn đã ở giới hạn, hãy chia việc ("viết phần 1/3") hoặc yêu cầu model tiếp tục từ câu cuối.

Đầu ra của MiniMax-M2.7 có giá $0.15 mỗi 1M token, rẻ hơn OpenRouter ở đầu ra.

Cùng một vấn đề dưới các tên khác nhau#

Các nhà cung cấp gắn nhãn khác nhau cho cùng nguyên nhân. Đây là những gì tài liệu của họ ghi tính đến ngày 20 tháng 10 năm 2026:

Nguồn: Mã lỗi DeepSeek, Lỗi API Claude. Cả hai trang đều không ghi ngày xuất bản, nên ngày kiểm tra là của chúng tôi.

Điều cần nhớ: đừng đoán từ câu chữ. Lỗi trả về dưới dạng JSON với một đối tượng error chứa type và message. Hãy khớp theo trạng thái và kiểu, vì nội dung thông báo thay đổi.

Xem thực tế trả về gì#

Đoạn mã này in trạng thái và nội dung của một yêu cầu thất bại và finish_reason của một yêu cầu thành công. Đây là bản phác thảo chẩn đoán, không phải nhật ký kiểm thử: chạy nó với khóa của bạn và đọc kết quả.

# Placeholders: YOUR_API_KEY, MODEL_ID (a model id you have access to)
from openai import OpenAI, APIStatusError

client = OpenAI(api_key="YOUR_API_KEY", base_url="https://api.cheaptokens.dev/v1")

try:
    r = client.chat.completions.create(
        model="MODEL_ID",
        messages=[{"role": "user", "content": "Write a long checklist."}],
        max_tokens=1000,
    )
except APIStatusError as e:
    # Read the status and the body, not the wording of the message
    print("status:", e.status_code)
    print("body:", e.body)
else:
    print("finish_reason:", r.choices[0].finish_reason)  # "length" = cut off
    print("usage:", r.usage)  # prompt_tokens and completion_tokens

Nếu kiểm tra chỉ ra số dư#

Nạp tiền vào số dư và gửi lại yêu cầu. Giá trên CheapTokens cố định theo model, không có giờ cao điểm, và một số dư bao trùm mọi model, nên bạn không cần nạp riêng cho từng model. Giá hiện tại ở đây:

Hãy đưa khối lượng của bạn vào bảng chi phí trước khi nạp tiền. Nạp tiền vào số dư khi các con số đã hợp lý, và nếu bạn muốn ước lượng khối lượng công việc lớn hơn trước, xem Cách ước lượng chi phí của một AI agent.