Lỗi của DeepSeek API đại thể chia thành bốn loại: xác thực, đường dẫn và tên mô hình, giới hạn tốc độ, quá thời gian. Thứ tự điều tra đúng là: trước hết xem mã trạng thái HTTP và loại lỗi, sau đó xem request ID và bản tái hiện tối thiểu, cuối cùng mới sửa prompt hoặc đổi mô hình. Đảo ngược thứ tự rất dễ biến vấn đề cấu hình thành vấn đề năng lực mô hình.
Bài viết tách riêng 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 giá mô hình trên trang.
Lưu ý: DeepSeek 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 theo phiên bản; 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. Phân biệt bốn loại lỗi trước
| Trạng thái hoặc hiện tượng | Ý nghĩa thường gặp | Nguyên nhân điển hình | Thứ tự xử lý |
|---|---|---|---|
| 401 | Xác thực thất bại | Key sai, thiếu Bearer, Key hết hiệu lực | Sửa thông tin xác thực trước |
| 404 | Đường dẫn hoặc mô hình không tồn tại | Base URL sai, tên mô hình cũ, ghép trùng đường dẫn | Kiểm tra địa chỉ và tên mô hình |
| 429 | Bị giới hạn tốc độ hoặc hạn mức | Đồng thời tăng vọt, dùng chung Key, bão thử lại | Lùi, giảm đồng thời |
| Quá thời gian | Quá thời gian kết nối hoặc đọc | Mạng, đầu ra dài, mô hình suy luận, proxy | Điều tra theo tầng |
| 400 | Tham số hoặc ngữ cảnh yêu cầu có vấn đề | Vượt ngữ cảnh, định dạng sai | Ước lượng rồi chia nhỏ |
| 5xx | Lỗi dịch vụ thượng nguồn | Sự cố hoặc quá tải phía máy chủ | Lùi, đổi kênh |
Trong log tối thiểu phải ghi thời gian, mã trạng thái, loại lỗi, tên mô hình, thời gian xử lý và request ID. Không ghi toàn bộ Key, cũng không in nguyên văn nội dung người dùng vào log.
2. 401: kiểm tra header trước, rồi kiểm tra Key
401 nghĩa là danh tính chưa được xác minh, thường không liên quan đến năng lực mô hình hay số dư. Điều tra theo thứ tự sau:
- Header có dùng
Authorization: Bearer <key>thay vì cách xác thực khác không. - Key có khoảng trắng, xuống dòng hoặc dấu ngoặc thừa ở đầu cuối không. Sao chép từ cửa sổ trò chuyện là dễ dính nhất.
- 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 vô hiệu hóa không.
- Base URL và Key có thuộc cùng một nền tảng không; Key chính thức cấu hình với địa chỉ cổng sẽ báo 401.
- Reverse proxy có ghi đè hoặc làm mất header
Authorizationkhông.
export DEEPSEEK_API_KEY="sk-khoa-cua-ban"
curl "https://api.deepseek.com/chat/completions" \
-H "Authorization: Bearer $DEEPSEEK_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"model": "deepseek-chat",
"messages": [{"role": "user", "content": "Chỉ trả lời OK"}],
"max_tokens": 16
}'
Lệnh này trả 200 nghĩa là Key, Base URL và tên mô hình đều thông. Nếu vẫn 401, hãy đổi một Key mới để làm yêu cầu tối thiểu, phân biệt vấn đề ở bản thân Key hay ở cấu hình proxy, cổng.
3. 404: địa chỉ và tên mô hình dễ sai nhất
404 thường không phải "giao diện hỏng", mà là yêu cầu đánh vào đường dẫn hoặc mô hình không tồn tại. Nguyên nhân phổ biến:
- Base URL viết thành địa chỉ nhà cung cấp khác, hoặc thừa, thiếu
/v1. - SDK tự ghép
/chat/completions, trong khi đường dẫn viết tay lại ghép thêm lần nữa. - Tên mô hình dùng phiên bản cũ đã ngừng cung cấp, hoặc khác chữ hoa chữ thường, khác hậu tố.
- Dùng lẫn địa chỉ cổng và địa chỉ chính thức vì quy tắc đường dẫn khác nhau.
- Quy tắc rewrite của reverse proxy làm hỏng đường dẫn.
Khi điều tra, trước hết dùng curl gọi địa chỉ đầy đủ, xác nhận thông tin lỗi trong phần thân phản hồi; sau đó đối chiếu từng mục Base URL và tên mô hình với trang giá trên site. Không nên hard-code nhiều địa chỉ trong mã; hãy cấu hình theo môi trường để tránh mang địa chỉ môi trường kiểm thử lên sản xuất.
4. 429: giới hạn tốc độ không phải thiếu số dư
429 nghĩa là yêu cầu vượt quá giới hạn tốc độ, đồng thời hoặc hạn mức. DeepSeek có thể giới hạn tốc độ hoặc xếp hàng yêu cầu vào giờ cao điểm; quy định cụ thể căn cứ theo tài liệu chính thức. Các tình huống kích hoạt phổ biến:
- Nhiều dịch vụ dùng chung một Key, chiếm hạn mức của nhau.
- Tác vụ hàng loạt khởi động cùng lúc đúng giờ tròn, tạo xung lưu lượng.
- Thử lại không lùi, càng thất bại càng gửi nhiều, tạo bão thử lại.
- Đầu ra dài hoặc tác vụ suy luận chiếm nhiều tài nguyên, không gian cho đồng thời bị thu hẹp.
| Hiện tượng | Nguyên nhân có thể | Xử lý |
|---|---|---|
| 429 tập trung vào giờ cao điểm | Tải thượng nguồn hoặc xung lưu lượng | Xếp hàng, gửi san đều, lệch giờ |
| Một Key nhiều dịch vụ bị 429 | Hạn mức bị chia sẻ | Tách Key theo dự án |
| Thử lại càng nặng hơn | Thử lại không lùi | Lùi cấp số nhân kèm nhiễu ngẫu nhiên |
| Yêu cầu dài bị 429 trước | Token đầu ra chiếm dụng cao | Giảm max_tokens hoặc đồng thời |
import random
import time
from openai import OpenAI, RateLimitError, APITimeoutError, APIStatusError
client = OpenAI(
api_key="sk-khoa-cua-ban",
base_url="https://api.deepseek.com",
max_retries=0, # Tắt tự thử lại của SDK để tránh chồng với logic riêng
)
def ask(prompt: str, retries: int = 4) -> str:
for attempt in range(retries):
try:
resp = client.chat.completions.create(
model="deepseek-chat",
messages=[{"role": "user", "content": prompt}],
max_tokens=1024,
timeout=60,
)
return resp.choices[0].message.content
except (RateLimitError, APITimeoutError):
wait = min(2 ** attempt, 20) + random.random()
print(f"Lần {attempt + 1} thất bại, chờ {wait:.1f} giây")
time.sleep(wait)
except APIStatusError as exc:
if exc.status_code >= 500:
wait = min(2 ** attempt, 20) + random.random()
time.sleep(wait)
continue
raise
raise RuntimeError("Đã dùng hết số lần thử lại")
print(ask("Dùng một câu giải thích thế nào là giới hạn tốc độ"))
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: phân biệt kết nối, đọc và truyền phát
Quá thời gian không đồng nghĩa dịch vụ không khả dụng; cần định vị nó kẹt ở đoạn nào:
| Hiện tượng | Nguyên nhân có thể | Xử lý |
|---|---|---|
| Quá thời gian kết nối | DNS, đầu ra mạng, proxy không tới được | Kiểm tra mạng và proxy, đổi tuyến |
| Token đầu tiên rất chậm | Thượng nguồn xếp hàng, prompt quá dài | Rút ngắn đầu vào, lệch giờ, đổi mô hình nhẹ |
| Quá thời gian đọc | Đầu ra quá dài, mô hình suy luận nghĩ lâu | Tăng thời gian chờ đọc, giới hạn đầu ra |
| Truyền phát bị ngắt | Mạng chập chờn, proxy cắt luồng | Hỗ trợ kết nối lại, ghi nội dung đã nhận |
| Toàn hệ thống cùng quá thời gian | Đầu ra cục bộ hoặc thượng nguồn gặp sự cố | Chuyển kênh dự phòng, xem trạng thái dịch vụ |
import httpx
from openai import OpenAI
client = OpenAI(
api_key="sk-khoa-cua-ban",
base_url="https://api.deepseek.com",
timeout=httpx.Timeout(connect=5.0, read=120.0, write=30.0, pool=10.0),
)
Thời gian chờ kết nối và thời gian chờ đọc phải đặt riêng. Đặt tất cả thành một giá trị rất lớn sẽ giữ thread pool khi sự cố; đặt quá nhỏ lại giết nhầm tác vụ dài bình thường. Cấu hình riêng theo loại tác vụ là cách ổn định hơn.
6. Bảng thứ tự điều tra
- Ghi mã trạng thái, loại lỗi, request ID, tên mô hình và thời điểm xảy ra.
- 401 kiểm tra Key, header, biến môi trường và nền tảng có khớp không.
- 404 kiểm tra Base URL, cách ghép đường dẫn và tên mô hình.
- 400 kiểm tra tham số, độ dài ngữ cảnh, định dạng ảnh hoặc tệp.
- 429 kiểm tra đồng thời, Key dùng chung, chiến lược thử lại và khung giờ cao điểm.
- Quá thời gian kiểm tra DNS, proxy, độ dài đầu ra và cấu hình thời gian chờ đọc.
- 5xx lùi và thử lại trước; nếu tiếp tục xuất hiện thì liên hệ bên cung cấp kèm request ID.
- Sau mỗi sự cố bổ sung giám sát và cảnh báo, đừng đợi phản hồi người dùng mới phát hiện.
7. Giám sát và log
| Trường | Mục đích |
|---|---|
| Thời gian và dự án | Định vị giờ cao điểm và phạm vi ảnh hưởng |
| Mã trạng thái và loại lỗi | Phân biệt xác thực, giới hạn tốc độ, lỗi thượng nguồn |
| Request ID | Chứng cứ then chốt để nhờ bên cung cấp điều tra |
| Tên mô hình và phiên bản | Xác định có phải xuất hiện sau khi đổi mô hình |
| Token vào ra | Phân tích chi phí và yêu cầu dài |
| Thời gian xử lý và số lần thử lại | Phát hiện độ trễ đuôi và bão thử lại |
Giám sát tối thiểu phải thống kê theo giờ số lượng 401, 404, 429, quá thời gian và 5xx. Khi tỷ lệ lỗi tăng vọt, trước hết xem có tập trung ở một dự án, một Key hay một mô hình không, rồi mới quyết định giảm đồng thời, chuyển kênh hay quay lui phiên bản.
Câu hỏi thường gặp
429 có phải do thiếu số dư không?
Không. 429 nghĩa là yêu cầu vượt quá giới hạn tốc độ, đồng thời hoặc hạn mức; thiếu số dư thường trả lỗi khác hoặc ghi rõ trong phần thân phản hồi. Hãy kiểm tra đồng thời và Key dùng chung trước, sau đó kiểm tra số dư tài khoản.
Nguyên nhân phổ biến nhất của 404 là gì?
Base URL sai, ghép trùng đường dẫn và tên mô hình hết hạn. Trước hết dùng curl gọi địa chỉ đầy đủ, rồi đối chiếu trang giá trên site để xác nhận tên mô hình; thường có thể định vị trong vài phút.
Quá thời gian có nên thử lại vô hạn không?
Không. Thử lại phải có giới hạn, lùi dần và cảnh báo; quá thời gian còn có thể nghĩa là yêu cầu đã được thực thi ở thượng nguồn. Nghiệp vụ có tác dụng phụ phải xác nhận trạng thái trước khi quyết định gửi lại.
Đầu ra truyền phát bị ngắt thì làm sao?
Trước hết ghi lại nội dung đã nhận và vị trí ngắt, sau đó xác định là mạng chập chờn, proxy cắt luồng hay thượng nguồn quá thời gian. Máy khách phải hỗ trợ kết nối lại và loại bỏ trùng lặp, không được đưa nửa nội dung vào cơ sở dữ liệu như kết quả hoàn chỉnh.
Phân biệt lỗi cổng và lỗi chính thức thế nào?
Giữ request ID và loại lỗi, dùng cùng một yêu cầu đánh lần lượt vào điểm vào chính thức và điểm vào cổng. Có thể nhanh chóng phân biệt vấn đề ở Key, mạng, cấu hình cổng hay dịch vụ thượng nguồn.
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.
Bài viết liên quan:
