Cách xử lý lỗi 401, 404, 429 và các mã lỗi thường gặp khi gọi API apicheap.store
Khi kết nối một công cụ (Claude Code, Codex, Cursor, SDK Python/Node) vào cổng API apicheap.store, đôi lúc bạn sẽ gặp một mã lỗi HTTP thay vì câu trả lời của mô hình. Tin tốt là các mã lỗi này đều có ý nghĩa rõ ràng và cách xử lý đơn giản. Bài này đi qua từng mã lỗi hay gặp nhất, giải thích nguyên nhân và chỉ cách sửa trong vài phút.
Cổng apicheap.store trả lỗi theo đúng hình dạng body của từng giao thức (OpenAI hoặc Anthropic), nên SDK của bạn tự hiểu được. Việc của bạn là đọc đúng mã số và làm theo hướng dẫn tương ứng.
Trước tiên: kiểm tra kết nối bằng một lệnh curl
Trước khi đoán lỗi, hãy gọi thử endpoint liệt kê model. Đây là phép thử nhanh nhất để biết API key có hợp lệ và server có nhận đúng không:
curl https://apicheap.store/v1/models \
-H "x-api-key: sk-YOUR_API_KEY"Nếu lệnh trên trả về danh sách model, nghĩa là key và kết nối đều ổn — lỗi (nếu có) nằm ở cấu hình model hoặc body request. Nếu lệnh trên đã báo lỗi, hãy đọc phần tương ứng bên dưới.
Server chấp nhận một trong ba dạng header xác thực, bạn chỉ cần dùng đúng một dạng:
x-api-key: sk-YOUR_API_KEY
anthropic-api-key: sk-YOUR_API_KEY
Authorization: Bearer sk-YOUR_API_KEYLỗi 401 — Thiếu hoặc sai API key
Đây là lỗi phổ biến nhất với người mới. Mã 401 nghĩa là server không nhận được API key hợp lệ: có thể bạn chưa đặt key, đặt sai biến môi trường, hoặc key đã bị vô hiệu hoá.
Cách xử lý:
- Kiểm tra giá trị key: phải bắt đầu bằng
sk-và là key còn hoạt động trong Portal. - Nếu dùng Claude Code, biến đúng là
ANTHROPIC_AUTH_TOKEN; nếu dùng SDK chuẩn OpenAI hoặc Codex thì làOPENAI_API_KEY. Đặt nhầm tên biến sẽ ra 401. Riêng Cursor, key được dán trong phần Settings của ứng dụng. - Sau khi đặt biến môi trường trên Windows hay macOS, hãy mở terminal mới để biến được nạp lại. Terminal đang mở sẵn không tự thấy biến vừa đặt.
- Dán thừa dấu cách hoặc dấu nháy quanh key cũng gây 401. Xoá sạch và dán lại đúng chuỗi key.
Nếu bạn đang cấu hình Claude Code CLI lần đầu, có thể xem lại các biến cần đặt trong bài kết nối Claude Code CLI với apicheap.store.
Lỗi 404 — Model không tồn tại hoặc chưa kích hoạt
Mã 404 nghĩa là tên model bạn gọi không có trong tài khoản, hoặc chưa được bật cho key đang dùng. Thường gặp khi bạn gõ tên combo chưa tạo, hoặc copy một tên model mẫu trong tài liệu mà quên thay bằng tên thật.
Cách xử lý:
- Gọi
GET /v1/models(lệnh curl ở trên) để lấy đúng danh sách tên model và combo đang bật cho tài khoản của bạn. - Nếu bạn muốn dùng combo (ví dụ tên minh hoạ
smart-live-combo), hãy chắc chắn đã tạo combo đó trong Portal ở tab "Bộ combo" trước khi điền tên vào cấu hình. Tên combo trong tài liệu chỉ là ví dụ; chưa tạo thì gọi sẽ ra lỗi. - Nếu chỉ muốn chạy ngay, hãy điền một mã model lẻ có trong danh sách (xem tab "Mô hình AI" trong Portal) thay vì combo.
Quy tắc chung: tên trong trường model phải khớp chính xác một mục mà GET /v1/models trả về.
Lỗi 400 — Body request không hợp lệ
Mã 400 xuất hiện khi JSON gửi lên bị sai cú pháp hoặc thiếu trường bắt buộc. Lỗi này thường do bạn tự viết request bằng curl hoặc code chứ ít khi do các công cụ dựng sẵn.
Cách xử lý:
- Với endpoint
/v1/messages(chuẩn Anthropic), **bắt buộc có trườngmax_tokens**. Thiếu nó là ra 400 ngay. - Kiểm tra body là JSON hợp lệ: đủ dấu ngoặc, dấu phẩy, không dư dấu phẩy cuối.
- Đặt header
Content-Type: application/jsonkhi gửi body JSON.
Ví dụ một request /v1/messages đúng chuẩn, có max_tokens và anthropic-version:
curl https://apicheap.store/v1/messages \
-H "x-api-key: sk-YOUR_API_KEY" \
-H "anthropic-version: 2023-06-01" \
-H "Content-Type: application/json" \
-d '{
"model": "smart-live-combo",
"max_tokens": 256,
"messages": [
{"role": "user", "content": "Hello"}
]
}'Lỗi 429 — Vượt giới hạn tốc độ (rate limit)
Mã 429 nghĩa là bạn gửi quá nhiều request trong thời gian ngắn. Thường gặp khi chạy nhiều luồng song song, hoặc một script gọi liên tục không nghỉ.
Cách xử lý:
- Đọc header
retry-aftertrong phản hồi rồi chờ đúng số giây đó mới thử lại. - Giảm số luồng chạy song song. Nếu đang bắn 10 request cùng lúc, hạ xuống 2–3 luồng và thêm khoảng nghỉ giữa các lần gọi.
- Áp dụng cơ chế thử lại có giãn cách (exponential backoff): mỗi lần lỗi thì chờ lâu hơn trước khi gọi lại.
429 không phải lỗi hỏng; nó chỉ là tín hiệu "chậm lại một chút". Khi giảm nhịp gọi, request sẽ qua bình thường.
Lỗi 502 và 503 — Sự cố phía mô hình
Hai mã này liên quan tới trạng thái của mô hình phía sau cổng, không phải do cấu hình của bạn.
- 502 là lỗi từ nhà cung cấp phía trên (upstream). Cách xử lý: thử lại sau giây lát. Nếu bạn đang dùng combo, hệ thống sẽ tự dự phòng sang nguồn khác, nên combo giúp giảm hẳn tình trạng này.
- 503 nghĩa là model đang tạm dừng hoặc bảo trì. Cách xử lý: đổi sang một model hoặc combo khác, hoặc xem lại trạng thái model trong Portal.
Đây chính là lý do tài liệu khuyến khích dùng combo định tuyến: khi một model gặp sự cố, combo tự chuyển tiếp sang model dự phòng để công việc của bạn không bị đứt quãng.
Mẹo: đếm token trước khi gọi để tránh bất ngờ
Nếu muốn ước lượng độ dài ngữ cảnh trước khi gửi, bạn có thể gọi endpoint đếm token. Endpoint này chỉ ước lượng số token đầu vào, không gọi mô hình nên không tốn phí:
curl https://apicheap.store/v1/messages/count_tokens \
-H "x-api-key: sk-YOUR_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"model": "smart-live-combo",
"messages": [{"role": "user", "content": "Hello"}]
}'Tóm tắt nhanh
- 401: key sai/thiếu hoặc nhầm tên biến môi trường → kiểm tra key và mở terminal mới.
- 404: tên model/combo không khớp → gọi
GET /v1/models, tạo combo trước khi dùng. - 400: body JSON sai hoặc thiếu
max_tokens→ sửa lại request. - 429: gọi quá nhanh → đọc
retry-after, giảm luồng song song. - 502 / 503: sự cố phía mô hình → thử lại hoặc đổi model; dùng combo để tự dự phòng.
Phần lớn lỗi khi tích hợp đều rơi vào 401 và 404, và cả hai đều sửa được trong một phút khi bạn biết nhìn đúng chỗ. Nếu cần xem lại thông số kết nối cho từng công cụ, hãy mở trang tài liệu kết nối API để lấy đúng Base URL, header và tên model cho tài khoản của bạn.