Docs / Giao thức

Xử lý sự cố

Triệu chứng → nguyên nhân → cách sửa, cho từng mã lỗi và cho các tool phổ biến.

Đọc lỗi trước đã

Mọi lỗi trả cùng một hình dạng nên một hàm xử lý là dùng được cho cả ba giao thức. Trường error.message thường đã nói nguyên nhân — đọc nó trước khi thử lại, vì thử lại một lỗi 4xx chỉ tốn thời gian.

{
  "type": "error",
  "error": {
    "type": "permission_error",
    "message": "key is not allowed to use \"claude-opus-5-5\""
  }
}

Theo mã lỗi

Mã	Message thường gặp	Nguyên nhân thật & cách sửa
401	missing api key	Request không mang key. Kiểm tra header: `Authorization: Bearer`, `x-api-key` (Anthropic SDK), hoặc `x-goog-api-key` (Google SDK).
401	invalid api key	Key sai, bị thu hồi, hoặc là key của dịch vụ khác. Key của chúng tôi bắt đầu bằng `sk-spk-`.
403	key revoked	Key đang tắt hoặc chưa kích hoạt (key mua bằng chuyển khoản chỉ bật khi tiền về). Bật lại ở trang API keys.
403	key is not allowed to use "x"	Model nằm ngoài danh sách của key. Mua key nhóm khác, hoặc gọi model mà key đó có.
404	model "x" is not available	Id model sai (thường do tool gửi id kèm hậu tố ngày). Gọi `GET /v1/models` để lấy id đúng.
400	body must be JSON	Body không parse được thành JSON. Hay gặp khi tự ghép chuỗi thay vì dùng SDK/JSON.stringify.
400	missing model	Body không có trường `model` (với Gemini thì model nằm trong PATH, không trong body).
402	credit exhausted	Hạn mức key đã tiêu hết. Nạp thêm cho key hoặc mua key mới.
402	credit remaining (...) is less than the worst-case cost	Hạn mức còn ít hơn chi phí XẤU NHẤT của request này. Hạ `max_tokens` là cách sửa nhanh nhất.
404	endpoint "/v1/xxx" is not supported	Endpoint nằm ngoài danh sách chúng tôi phục vụ (embeddings, images, audio, files, batches…). Chỉ có `/v1/messages`, `/v1/messages/count_tokens`, `/v1/chat/completions`, `/v1/responses`, `/v1/models` và `/v1beta/models/...`.
405	method not allowed	Gọi sai HTTP method: các endpoint trên chỉ nhận POST (trừ `GET /v1/models`).
413	request body too large	Body vượt 32 MB. Ảnh base64 cỡ vài chục MB là nguyên nhân thường gặp — nén hoặc crop trước.
429	rate limit 600 rpm exceeded	Quá 600 request/phút cho key này. Chờ đúng số giây trong header `retry-after`.
429	too many concurrent requests (max N per key)	Quá 500 request ĐANG CHẠY cùng lúc trên một key (stream chưa đóng cũng tính). Giảm song song hoặc chờ.
429	too many failed authentication attempts	Cùng một IP gửi quá nhiều key sai trong 60 giây — chặn tạm để chống dò key. Kiểm tra lại key rồi chờ hết `retry-after`.
429	upstream rate limited	Nhà cung cấp đang rate limit và mọi kênh đều đã thử. Thử lại sau; giảm song song nếu lặp lại nhiều.
502	no healthy upstream for this model	Nhà cung cấp của model đó đang không có kênh khoẻ. Thử model khác hoặc thử lại sau.
502	upstream returned XXX	Nhà cung cấp trả lỗi. Lỗi 5xx thì thử lại; 4xx thì request sai tham số cho model đó.
502	upstream authentication failed	Lỗi phía chúng tôi (credential kênh). Báo hỗ trợ kèm thời điểm và model.

Tool không nhận key

Triệu chứng	Nguyên nhân & cách sửa
Claude Code báo 404 model	Claude Code tự gửi id kèm hậu tố ngày (vd `claude-sonnet-4-5-20250929`) mà chúng tôi chỉ bán id trần. Đặt `ANTHROPIC_MODEL` = id trong `GET /v1/models`.
Tool OpenAI-compatible (Cline, Continue, OpenCode, OpenClaw) báo 404 khi chọn model `claude-*`	Tool gửi request theo `/v1/chat/completions` — đường đó không tồn tại ở Anthropic. Đổi provider sang Anthropic/`anthropic-messages` với base URL `https://api.apimodelhub.com` (không `/v1`), hoặc dùng Claude Code/Codex cho model Claude.
Tool Anthropic báo 404 khi chọn model `gpt-*`	Ngược lại trường hợp trên: `/v1/messages` không có ở OpenAI. Model GPT/Grok/DeepSeek phải đi `/v1/chat/completions` hoặc `/v1/responses`.
Tool gọi `/chat/completions` ở gốc domain → 404	Base URL thiếu `/v1`. Điền `https://api.apimodelhub.com/v1` (SDK tự nối path), không phải cả endpoint đầy đủ.
Dán `https://api.apimodelhub.com/v1` vào SDK Anthropic → 404	SDK Anthropic tự nối `/v1/messages`, nên base URL phải là `https://api.apimodelhub.com` — thêm `/v1` thành `/v1/v1/messages`.
Tool hỏi "base URL" mà dán vào lại lỗi đường dẫn	Phân biệt hai kiểu: ô "base URL" nhận `https://api.apimodelhub.com/v1`; ô "full endpoint" nhận `https://api.apimodelhub.com/v1/chat/completions`.
Cursor cấu hình được nhưng model Claude không gọi được	Cursor chỉ override được base URL của phần OpenAI (BYOK). Model Claude trong Cursor do backend của Cursor phục vụ, không đi qua chúng tôi.
Stream bị cắt giữa chừng	Kiểm tra client timeout (đặt ≥ 120s cho request dài). Request stream chưa đóng cũng chưa được ghi vào lịch sử sử dụng.
Model OpenAI thế hệ mới báo 400 về `max_tokens`	Chỉ xảy ra ở `/v1/responses`: ở `/v1/chat/completions` chúng tôi tự đổi sang `max_completion_tokens`; ở `/v1/responses` bạn phải tự gửi đúng tên tham số.

Nghi ngờ tính tiền sai

Mở trang Lịch sử sử dụng → tab chi tiết, xem đúng request đó (token in/out và số tiền bị trừ).
So với giá trong GET /v1/models: cột pricing_usd_per_1m là giá BÁN đang áp dụng.
Nhớ đơn vị: hạn mức key trừ theo GIÁ GỐC provider, không theo giá bán — xem trang "Key & hạn mức".
Nếu vẫn lệch, gửi chúng tôi id request và thời điểm; sổ được ghi sau mỗi request nên tra được chính xác.

Đừng suy ra tiền từ số token nhìn thấy trong responseResponse có thể không trả usage đầy đủ (một số đường stream ẩn chunk usage để client thấy y như khi gọi trực tiếp). Con số đáng tin là trong Lịch sử sử dụng, vì đó là số dùng để trừ tiền.