Lỗi của GLM API có hai lớp: lớp ngoài là mã trạng thái HTTP, lớp trong là mã nghiệp vụ trong phần thân phản hồi. Chỉ nhìn lớp ngoài rất dễ đánh giá sai, ví dụ tài khoản nợ phí cũng trả 429. Thứ tự điều tra nên là: trước hết đọc mã nghiệp vụ và thông tin lỗi, sau đó tìm request ID hoặc error ID, rồi dùng yêu cầu tối thiểu tái hiện, cuối cùng mới sửa tham số hoặc đổi mô hình.
Bài viết tách riêng 401, 403, 404, 429, 5xx và quá thời gian, đưa ra bảng đối chiếu mã nghiệp vụ, mã xử lý lỗi và danh sách trước khi liên hệ hỗ trợ. Mô hình và giá căn cứ theo giá mô hình trên site.
Lưu ý: Zhipu, GLM và BigModel là nhãn hiệu của các chủ sở hữu quyền tương ứng; bài viết chỉ nhằm giải thích kỹ thuật, không có quan hệ trực thuộc hay đại lý với Zhipu. Mã 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; cuối cùng căn cứ theo tài liệu chính thức và phản hồi thực tế.
1. Phân biệt hai lớp lỗi trước
Mã trạng thái HTTP cho biết kết cục ở lớp giao thức, mã nghiệp vụ cho biết nguyên nhân cụ thể. Cùng một 401 có thể do thiếu header xác thực, Token hết hạn hoặc xác thực hai lớp; cùng một 429 có thể do giới hạn tốc độ, mô hình bận, nợ phí hoặc vượt hạn mức gói. Ghi mã nghiệp vụ vào log là bước nâng hiệu quả điều tra cao nhất.
| HTTP | Mã nghiệp vụ thường gặp | Ý nghĩa | Có phù hợp thử lại không |
|---|---|---|---|
| 401 | 1000 / 1001 / 1003 / 1005 | Xác thực thất bại, thiếu header, Token hết hạn, xác thực hai lớp | Không, sửa thông tin xác thực trước |
| 403 | 1220 | Không có quyền truy cập API hoặc mô hình đó | Không, kiểm tra gói và quyền |
| 400 | 1210 / 1211 / 1221 / 1222 / 1261 | Tham số sai, mô hình không tồn tại, API ngừng hoặc không tồn tại, Prompt quá dài | Không, sửa yêu cầu |
| 429 | 1113 | Tài khoản nợ phí | Không, nạp tiền trước |
| 429 | 1302 / 1305 | Giới hạn tốc độ, lượng truy cập mô hình quá lớn | Có, lùi rồi thử lại |
| 429 | 1308 / 1310 | Vượt hạn mức chu kỳ, đặt lại theo next_flush_time | Đợi đặt lại, không thử lại cứng |
| 429 | 1311 / 1313 / 1315 | Gói không có quyền mô hình, giới hạn sử dụng công bằng, loại Key không khớp | Không, kiểm tra gói và Key |
| 500 | 1200 / 1230 / 1234 | Lỗi nội bộ, lỗi quy trình, lỗi mạng (kèm error ID) | Có, lùi và giữ error ID |
Bảng trên là các ánh xạ phổ biến nhất; danh sách đầy đủ căn cứ theo tài liệu chính thức. Truyền phát bị ngắt có thể không có mã nghiệp vụ; nguyên nhân thể hiện trong finish_reason hoặc đoạn dữ liệu cuối.
2. 401: bốn kiểu xác thực thất bại
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ư. Mã lỗi chính thức phân loại khá chi tiết:
- 1000 xác thực danh tính thất bại: Key sai, sao chép không đầy đủ hoặc đã bị xóa.
- 1001 header thiếu tham số xác thực: không có
Authorization: Bearer <key>, hoặc bị proxy làm mất. - 1003 Token đã hết hạn: Key có thời hạn, hoặc đã bị luân chuyển trong bảng điều khiển.
- 1005 đã bật xác thực hai lớp: hoàn tất xác minh theo yêu cầu nền tảng.
Điều tra theo thứ tự:
- Xác nhận định dạng header: một dấu cách sau dấu hai chấm, Key không có dấu ngoặc hoặc xuống dòng ở đầu cuối.
- In phần đầu biến môi trường, xác nhận không phải giá trị rỗng hoặc giá trị cũ.
- Xác nhận loại Key: API mô hình tiêu chuẩn, Coding Plan, Key nhóm hoặc doanh nghiệp quản lý riêng, không dùng lẫn.
- Xác nhận Base URL và Key cùng thuộc một hệ thống: Key chính thức đi với địa chỉ chính thức, Key cổng đi với địa chỉ cổng.
- Đổi một Key mới làm yêu cầu tối thiểu, phân biệt vấn đề Key với vấn đề cấu hình proxy, cổng.
Sao chép Key từ cửa sổ chat dễ mang theo khoảng trắng hoặc xuống dòng nhất. Trước hết làm một yêu cầu chỉ trả về một từ, có thể loại trừ phần lớn lỗi sơ đẳng.
3. 403 và 404: quyền, đường dẫn và tên mô hình
Mã nghiệp vụ phổ biến của 403 là 1220, nghĩa là tài khoản hiện tại không có quyền truy cập API hoặc mô hình đó. Trước hết kiểm tra gói có bao gồm mô hình đó không, Key có thuộc đúng loại sản phẩm không, rồi kiểm tra có gọi giao diện chưa mở không. Loại lỗi này thử lại vô ích; hãy sửa quyền hoặc đổi Key.
404 phần lớn không phải "dịch vụ sập" mà là địa chỉ sai: Base URL thừa hoặc thiếu /v1, SDK tự ghép xong lại viết tay toàn bộ đường dẫn, quy tắc rewrite của reverse proxy làm hỏng đường dẫn. Tên mô hình sai của GLM thường trả 400 với mã 1211; API ngừng hoặc không tồn tại tương ứng 1221 và 1222. Vì vậy thấy 404 hãy kiểm tra địa chỉ trước, thấy 1211 mới kiểm tra tên mô hình.
Tên mô hình căn cứ theo tài liệu chính thức và trang giá trên site, đừng viết số phiên bản theo trí nhớ. Khi nâng cấp mô hình, trước hết xác nhận tham số tương thích trong môi trường kiểm thử.
4. 429: đọc mã nghiệp vụ trước, rồi quyết định có thử lại
429 là lỗi dễ bị xử lý sai nhất. Nó ít nhất gồm năm trường hợp:
- 1113 tài khoản nợ phí: thử lại trước khi nạp tiền không có ý nghĩa.
- 1302 đạt giới hạn tốc độ: giảm đồng thời hoặc lùi.
- 1305 lượng truy cập mô hình hiện tại quá lớn: thường liên quan giờ cao điểm, lùi rồi thử lại, cần thiết thì chuyển mô hình dự phòng.
- 1308, 1310 đạt hạn mức sử dụng chu kỳ: thông tin lỗi có thời điểm đặt lại, đợi hạn mức khôi phục.
- 1309, 1311, 1313, 1315: gói hết hạn, mô hình chưa mở, giới hạn sử dụng công bằng hoặc loại Key không khớp; chỉ sửa cấu hình mới có tác dụng.
Chỉ các giới hạn tức thời như 1302, 1305 mới phù hợp thử lại tự động; các trường hợp còn lại thử lại chỉ kéo dài thời gian sự cố. Quy định giới hạn tốc độ (đồng thời, số yêu cầu mỗi phút hoặc tốc độ Token) thay đổi theo gói và mô hình; căn cứ theo bảng điều khiển và tài liệu chính thức.
5. 5xx và quá thời gian: định vị riêng
Dòng 500 gồm 1200 lỗi nội bộ, 1230 lỗi quy trình, 1234 lỗi mạng. 1234 thường kèm error ID; khi liên hệ hỗ trợ nhất định phải giữ lại. 5xx liên tục thì lùi trước, rồi xem trạng thái dịch vụ hoặc thông báo của bên cung cấp, không thử lại tần suất cao.
Quá thời gian cần xem theo ba đoạn: quá thời gian kết nối là DNS, đầu ra hoặc proxy không tới được; token đầu tiên chậm thường do thượng nguồn xếp hàng hoặc đầu vào quá dài; quá thời gian đọc phần lớn do đầu ra quá dài hoặc suy luận lâu. Cách xử lý ba loại khác nhau, không thể chỉ tăng thời gian chờ.
Khi yêu cầu truyền phát bị ngắt, có thể không có mã lỗi HTTP lẫn mã nghiệp vụ. Trước hết ghi nội dung đã nhận và đoạn dữ liệu cuối, kiểm tra finish_reason, rồi xác định là mạng chập chờn, proxy cắt luồng hay thượng nguồn quá thời gian. Không được đưa nửa nội dung vào cơ sở dữ liệu như kết quả hoàn chỉnh.
6. Request ID và log: chứng cứ điều tra
Phản hồi chính thức không nhất thiết cung cấp cùng một tên request ID ở mọi giao diện; tên trường căn cứ theo phản hồi thực tế và tài liệu. Cách ổn định hơn về kỹ thuật là ghi hai đường: máy khách tạo trace_id xuyên suốt mọi lần thử lại; đồng thời lưu nguyên trạng phần thân lỗi thượng nguồn và mọi trường request id, error id trong đó.
Log tối thiểu gồm: thời gian, trace_id, Base URL, tên mô hình, mã trạng thái HTTP, mã nghiệp vụ, thông tin lỗi, thời gian xử lý, số lần thử lại, có truyền phát hay không. Key chỉ ghi vài ký tự đầu hoặc mã băm; nội dung gốc của người dùng và toàn bộ phản hồi không được ghi nguyên đoạn xuống đĩa.
Những trường này không chỉ để tự xem. Khi liên hệ hỗ trợ, một bản ghi có trace_id, mã nghiệp vụ và yêu cầu tái hiện tối thiểu hữu ích hơn nhiều so với một câu "thỉnh thoảng báo lỗi".
7. Thử lại và lùi: ví dụ mã
Đoạn mã dưới đây tắt tự thử lại của SDK, quyết định có thử lại theo mã nghiệp vụ, đồng thời in trace_id, mã trạng thái và mã nghiệp vụ. Quá thời gian mạng xử lý riêng, thử lại có giới hạn.
import os
import random
import time
import uuid
import httpx
from openai import OpenAI, APIConnectionError, APIStatusError, APITimeoutError
client = OpenAI(
api_key=os.environ["GLM_API_KEY"],
base_url=os.environ.get(
"GLM_BASE_URL", "https://open.bigmodel.cn/api/paas/v4"
),
timeout=httpx.Timeout(connect=5.0, read=120.0, write=30.0, pool=10.0),
max_retries=0, # Tắt tự thử lại của SDK, để logic bên dưới kiểm soát thống nhất
)
RETRYABLE_CODES = {1302, 1305} # Giới hạn tốc độ, mô hình bận; nợ phí và hạn mức gói không nằm trong đây
def ask(prompt: str, max_attempts: int = 4) -> str:
trace_id = uuid.uuid4().hex[:12]
for attempt in range(1, max_attempts + 1):
try:
resp = client.chat.completions.create(
model=os.environ["GLM_MODEL"],
messages=[{"role": "user", "content": prompt}],
max_tokens=1024,
)
return resp.choices[0].message.content
except APIStatusError as exc:
code = None
try:
code = int(exc.response.json().get("code"))
except Exception:
pass
print(
f"trace={trace_id} attempt={attempt} "
f"http={exc.status_code} code={code} "
f"body={exc.response.text[:500]}"
)
retryable = exc.status_code >= 500 or (
exc.status_code == 429 and code in RETRYABLE_CODES
)
if not retryable or attempt == max_attempts:
raise
except (APITimeoutError, APIConnectionError) as exc:
print(f"trace={trace_id} attempt={attempt} err={type(exc).__name__}")
if attempt == max_attempts:
raise
wait = min(2 ** (attempt - 1), 20) + random.uniform(0, 1)
time.sleep(wait)
raise RuntimeError("Đã dùng hết số lần thử lại")
Bổ sung ba quy tắc: ưu tiên tôn trọng Retry-After do máy chủ trả về (nếu có); ngân sách thử lại phải kiểm soát toàn cục, tránh nhiều dịch vụ cộng dồn; yêu cầu có tác dụng phụ phải dùng khóa lũy đẳng xác nhận trạng thái trước khi quyết định gửi lại.
8. Quản trị đồng thời: hiệu quả hơn tăng thử lại
Vấn đề giới hạn tốc độ thường không giải quyết bằng thử lại, mà bằng quản trị điểm vào:
- Mỗi dịch vụ đặt Key riêng và giới hạn đồng thời riêng.
- Tác vụ hàng loạt chia mảnh, lệch giờ, tránh xung lưu lượng đúng giờ tròn.
- Dùng hàng đợi san đỉnh, tác vụ thất bại vào hàng đợi trễ thay vì quay tại chỗ.
- Giám sát tỷ lệ 429 và độ trễ P95; khi tăng vọt thì giảm đồng thời trước.
- Chuẩn bị mô hình dự phòng hoặc điểm vào dự phòng, nhưng xác nhận tham số tương thích trước khi chuyển.
Giới hạn đồng thời, số yêu cầu mỗi phút và tốc độ Token cụ thể thay đổi theo gói và mô hình; căn cứ theo bảng điều khiển và tài liệu chính thức. Đừng sao chép con số của người khác, hãy đặt theo kết quả đo thực tế của bạn.
9. Danh sách trước khi liên hệ hỗ trợ
- Thời điểm xảy ra và múi giờ, sự cố có bùng phát tập trung không.
- Base URL, đường dẫn giao diện, tên mô hình và phương thức yêu cầu.
- Mã trạng thái HTTP, mã nghiệp vụ và thông tin lỗi đầy đủ.
- Error ID hoặc request ID; nếu không có thì cung cấp
trace_idtự tạo. - Một yêu cầu curl tối thiểu có thể tái hiện, Key đã khử nhận dạng.
- Có truyền phát không, có ngữ cảnh dài không, có vừa sửa cấu hình không.
- Phạm vi ảnh hưởng: một Key, một dự án hay toàn bộ dịch vụ.
Chuẩn bị đủ các mục này, đội hỗ trợ mới định vị trực tiếp được, thay vì hỏi qua lại. 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.
10. Câu hỏi thường gặp (FAQ)
1. 429 có nhất định là giới hạn tốc độ không?
Không nhất định. 429 còn có thể là nợ phí (1113), vượt hạn mức chu kỳ (1308, 1310), gói không có quyền mô hình (1311) hoặc giới hạn sử dụng công bằng (1313). Đọc mã nghiệp vụ trước, rồi quyết định lùi, nạp tiền hay sửa cấu hình.
2. 401 đổi Key mới vẫn thất bại thì làm sao?
Kiểm tra header có phải Authorization: Bearer <key> không, biến môi trường có được nạp không, loại Key có khớp giao diện không, Base URL và Key có cùng hệ thống không, và reverse proxy có làm mất header xác thực không.
3. Quá thời gian có nên thử lại không?
Chỉ thử lại có giới hạn với lỗi kết nối và quá thời gian đọc, đồng thời đặt lùi cấp số nhân. Nghiệp vụ có tác dụng phụ phải xác nhận đã thực thi chưa, tránh đặt hàng hoặc ghi dữ liệu trùng.
4. Đầu ra truyền phát đứt giữa chừng thì điều tra thế nào?
Ghi nội dung đã nhận, đoạn dữ liệu cuối và finish_reason, phân biệt mạng chập chờn, proxy cắt luồng và 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 đưa nửa nội dung vào cơ sở dữ liệu.
5. Thông tin lỗi chỉ có mã trạng thái không có mã nghiệp vụ thì làm sao?
Giữ toàn bộ phần thân và header phản hồi, ghi trace_id, Base URL, tên mô hình và yêu cầu tái hiện tối thiểu, rồi liên hệ bên cung cấp. Khi đi qua cổng cũng cung cấp các thông tin này cho bên cổng để đối chiếu log 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, 403, 429, 5xx 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à cách tính phí xem tại giá mô hình.
