Mã lỗi API: cách xử lý lỗi 401, 403, 404, 429 và 5xx

Ý nghĩa và cách xử lý các lỗi 401, 403, 404, 429, 5xx của 88API, gồm token không hợp lệ, thiếu số dư, gửi yêu cầu quá nhanh và lỗi Claude Code, Codex.

Khi gọi thất bại, API sẽ trả về mã trạng thái HTTP và một đoạn JSON, nguyên nhân lỗi nằm trong error.message:

{
  "error": {
    "code": "",
    "message": "Invalid token (request id: 2026101605444223...)",
    "type": "new_api_error"
  }
}

request id ở cuối message là mã số của yêu cầu này; hãy cung cấp kèm khi liên hệ chăm sóc khách hàng. Trang Nhật ký sử dụng trong bảng điều khiển cũng ghi lại thời gian, mô hình và thông tin lỗi của các yêu cầu thất bại. Khi kiểm tra, hãy xem mã trạng thái trước, sau đó xem message.

Thông báo lỗi theo ngôn ngữ đã lưu trong hồ sơ của bạn (hoặc header Accept-Language của ứng dụng). Nếu không có, thông báo có thể trả về bằng tiếng Trung; ý nghĩa giống như mô tả bên dưới.

Bảng tra nhanh

Mã trạng thái	Ý nghĩa	Việc cần làm trước
400	Nội dung hoặc tham số yêu cầu không được mô hình chấp nhận	Sửa tham số, prompt hoặc hình ảnh theo thông tin lỗi
401	Token không hợp lệ	Kiểm tra API Key đã điền đúng chưa, có bị xóa chưa
403	Token không khả dụng, thiếu số dư hoặc không có quyền	Kiểm tra số dư, trạng thái token, nhóm và giới hạn mô hình của token
404	Địa chỉ hoặc mô hình không tồn tại	Kiểm tra địa chỉ API có thừa `/v1` không, tên mô hình có khả dụng trong nhóm hiện tại không
429	Gửi yêu cầu quá nhanh hoặc mô hình đang bận	Giảm tần suất, thử lại sau
500, 502, 503, 504, 524	Dịch vụ mô hình tạm thời không khả dụng hoặc quá thời gian chờ	Thử lại sau; nếu vẫn thất bại, đổi nhóm hoặc đổi mô hình

401: Token không hợp lệ

Thông báo thường gặp: Invalid token, 无效的令牌 (token không hợp lệ).

API Key sao chép không đầy đủ, hoặc có khoảng trắng, xuống dòng ở đầu hoặc cuối.
Token đã bị xóa trong bảng điều khiển. Hãy tạo mới hoặc sao chép lại tại trang Mã thông báo API.
Claude Code: đồng thời đang đặt biến ANTHROPIC_API_KEY cũ. Biến này được ưu tiên hơn ANTHROPIC_AUTH_TOKEN, hãy xóa nó và chỉ giữ lại ANTHROPIC_AUTH_TOKEN.
Cách viết header yêu cầu: định dạng OpenAI dùng Authorization: Bearer sk-...; định dạng Anthropic dùng x-api-key: sk-....

403: Token không khả dụng, thiếu số dư hoặc không có quyền

Thiếu số dư hoặc hạn mức

Thông báo thường gặp: Insufficient user quota, Not enough quota to pre-consume for this request: … remaining, … required.

Số dư tài khoản không đủ cho khoản trừ trước của yêu cầu này. Hãy nạp tiền tại trang Ví.
Tài khoản còn số dư nhưng vẫn báo không đủ: token có thể được đặt giới hạn hạn mức riêng, hãy kiểm tra hạn mức còn lại của token đó.
Claude Code sẽ hiển thị loại lỗi 403 này thành lỗi xác thực hoặc «API Error 403», cách xử lý giống nhau.

Trạng thái token không khả dụng

Thông báo thường gặp: This token status is unavailable.

Token đã bị vô hiệu hóa, đã hết hạn hoặc đã dùng hết hạn mức. Tại trang Mã thông báo API, hãy bật token, sửa thời gian hết hạn hoặc điều chỉnh hạn mức.

Không có quyền với nhóm hoặc mô hình

Thông báo thường gặp: No permission to access group …, API Key 所属专属分组不再允许当前用户使用 (nhóm chuyên dụng mà API Key này thuộc về không còn cho phép người dùng hiện tại sử dụng), This token has no access to model ….

Tài khoản hiện tại không dùng được nhóm mà token đang gắn: hãy sửa token, đổi sang nhóm khả dụng trong Quảng trường mô hình.
Token có đặt giới hạn mô hình: mở quyền cho mô hình tương ứng trong cài đặt token, hoặc dùng một token khác.

Nhóm hiện tại không hỗ trợ giao diện này

Thông báo thường gặp: This group does not allow /v1/messages dispatch.

Nhóm đã chọn không hỗ trợ giao diện của giao thức này (ví dụ dùng nhóm chỉ hỗ trợ định dạng OpenAI để gọi /v1/messages của Anthropic). Với Claude Code, hãy dùng token thuộc nhóm Claude; các ứng dụng khác hãy gọi theo loại giao diện mà mô hình hỗ trợ trong Quảng trường mô hình.

404: Địa chỉ hoặc mô hình không tồn tại

Địa chỉ thừa hoặc thiếu /v1

Thông báo thường gặp: Invalid URL, 404 page not found.

ANTHROPIC_BASE_URL của Claude Code điền https://api.88api.ai, không thêm /v1 (Claude Code tự nối thêm /v1/messages, nếu viết .../v1 sẽ thành /v1/v1/messages).
base_url của Codex điền https://api.88api.ai/v1, bắt buộc có /v1.
Phần lớn ứng dụng tương thích OpenAI điền https://api.88api.ai/v1. Cách điền cho từng ứng dụng xem hướng dẫn kết nối ứng dụng.

Mô hình không khả dụng trong nhóm hiện tại

Thông báo thường gặp: No available channel for model … under group …, Model "…" is not supported by any configured account in this group, model not found.

Tên mô hình viết sai, hoặc có thêm tiền tố, hậu tố thừa. Hãy sao chép tên mô hình chính xác trong Cài đặt hồ sơ hoặc Quảng trường mô hình.
Mô hình không có trong nhóm mà token đã chọn. Xem mô hình hỗ trợ những nhóm nào trong Quảng trường mô hình, sau đó sửa nhóm của token.

400: Nội dung hoặc tham số yêu cầu không được chấp nhận

Thông báo lỗi (ví dụ)	Nguyên nhân và cách xử lý
`输入内容超过模型上下文限制` (nội dung đầu vào vượt quá giới hạn ngữ cảnh của mô hình), `Input exceeds the context limit`	Cuộc hội thoại quá dài. Hãy rút gọn lịch sử hoặc mở phiên mới; trong Claude Code có thể dùng `/compact` để nén ngữ cảnh
`请求中包含该模型不支持的参数（如 presence_penalty / frequency_penalty）` (yêu cầu chứa tham số mà mô hình này không hỗ trợ, như presence_penalty / frequency_penalty)	Bỏ tham số được nhắc đến trong thông báo lỗi
`该模型是生图模型，不能通过对话接口调用` (mô hình này là mô hình tạo ảnh, không thể gọi qua giao diện hội thoại)	Tạo ảnh hãy dùng `/v1/images/generations`, sửa ảnh dùng `/v1/images/edits`, xem API hình ảnh
`please use the Gemini native API`	Mô hình này chỉ hỗ trợ định dạng gốc của Gemini, xem API Gemini
`the selected model cannot disable reasoning`, `不支持关闭深度思考` (không hỗ trợ tắt chế độ suy nghĩ sâu)	Mô hình này bắt buộc bật suy nghĩ, hãy bỏ tham số tắt suy nghĩ (hoặc đặt loại suy nghĩ là enabled)
`requires adaptive thinking`	Mô hình Claude này yêu cầu suy nghĩ thích ứng: bỏ tham số `thinking`, hoặc đổi thành `type=adaptive` theo gợi ý trong thông báo lỗi
`当前输入触发平台内容安全规则` (nội dung đầu vào vi phạm quy tắc an toàn nội dung của nền tảng), `未通过内容安全审核` (không vượt qua kiểm duyệt an toàn nội dung), `可能违反了…内容政策` (có thể vi phạm chính sách nội dung của …)	Prompt hoặc ảnh tham chiếu bị kiểm duyệt an toàn chặn, hãy sửa nội dung rồi thử lại
`Failed to download multimodal content`, `mime type is not supported`	Không truy cập được địa chỉ ảnh hoặc định dạng không được hỗ trợ. Hãy đổi sang ảnh PNG, JPEG, WebP có thể truy cập công khai, hoặc dùng base64

429: Gửi yêu cầu quá nhanh hoặc đang bận

Vượt giới hạn tần suất yêu cầu của tài khoản

Thông báo thường gặp: Your request rate is too high. The current user group allows up to … successful requests within a …-minute window.

Giới hạn mặc định là 60 RPM (số yêu cầu mỗi phút). Hãy giảm số yêu cầu đồng thời hoặc thêm khoảng chờ thử lại trong ứng dụng; nếu thật sự cần tần suất cao hơn, có thể liên hệ chăm sóc khách hàng để xin nâng giới hạn.

Mô hình đang bận

Thông báo thường gặp: Upstream rate limit exceeded, service error, please try again later, Concurrency limit exceeded.

Mô hình hiện có lượng yêu cầu lớn. Hãy chờ vài giây rồi thử lại; nếu cần ổn định, có thể đổi sang nhóm khác trong Quảng trường mô hình.

500, 502, 503, 504, 524: Dịch vụ tạm thời không khả dụng hoặc quá thời gian chờ

Thông báo thường gặp: Upstream service temporarily unavailable, Service temporarily unavailable. Please retry., 系统过载，请稍后重试 (hệ thống quá tải, vui lòng thử lại sau), 模型请求失败，请稍后重试或更换模型 (yêu cầu tới mô hình thất bại, vui lòng thử lại sau hoặc đổi mô hình), bad response status code 504.

Loại lỗi này phần lớn do dịch vụ mô hình tạm thời bận hoặc mạng dao động, thường thử lại là hết. Nên để ứng dụng thử lại với khoảng chờ tăng dần 1 giây, 2 giây, 4 giây.
Khi cùng một mô hình liên tục thất bại, hãy đổi sang nhóm khác hoặc mô hình khác.
524, 504 thường xảy ra với các yêu cầu cần thời gian tạo rất lâu: với yêu cầu hội thoại hãy bật xuất dạng luồng (stream: true); với tạo ảnh, video hãy dùng giao diện tác vụ bất đồng bộ để truy vấn kết quả.

Vẫn chưa giải quyết được

Tìm bản ghi thất bại trong Nhật ký sử dụng, gửi thời gian yêu cầu, tên mô hình, mã trạng thái và toàn bộ thông báo lỗi (gồm request id) cho chăm sóc khách hàng trực tuyến. Không gửi toàn bộ API Key của bạn.

Mã lỗi và các lỗi thường gặp