Các lỗi kết nối thường gặp và cách khắc phục

Hầu hết mọi vấn đề kết nối đều quy về bốn thứ: địa chỉ, khóa, ID model và số dư. Hãy bắt đầu với bước kiểm tra nhanh bên dưới, rồi tìm mã trạng thái của bạn. Các phần thân phản hồi được trích dẫn ở đây là phản hồi thực tế của API (tháng 10 năm 2026).

Kiểm tra nhanh#

# 1. The address is reachable — this request needs no key
curl https://api.cheaptokens.dev/v1/models

# 2. The key and the balance work — a tiny request (costs a fraction of a cent)
curl https://api.cheaptokens.dev/v1/chat/completions \
  -H "Authorization: Bearer $CHEAPTOKENS_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"model": "deepseek-ai/DeepSeek-V4-Flash-0731", "max_tokens": 5,
       "messages": [{"role": "user", "content": "ping"}]}'

Nếu lệnh đầu tiên thất bại, nguyên nhân có thể là mạng phía bạn, lỗi gõ trong địa chỉ — hoặc chính dịch vụ tạm thời không khả dụng. Nếu chỉ lệnh thứ hai thất bại, hãy tra mã trạng thái của nó bên dưới. Nếu cả hai đều hoạt động nhưng công cụ của bạn thì không, hãy so sánh cài đặt của công cụ với hai lệnh này.

401 — Khóa API không hợp lệ#

{"error": {"message": "Invalid API key", "type": "authentication_error"}}

Các client theo phong cách Anthropic nhận cùng lỗi ở định dạng của chúng:

{"type": "error", "error": {"type": "authentication_error", "message": "Invalid API key"}}

Nguyên nhân:

• khóa bị sao chép thiếu ký tự, có dấu cách hoặc dấu ngoặc kép;
• khóa đã bị xoay trong dashboard — khóa cũ không còn hoạt động;
• đặt khóa từ dịch vụ khác (ví dụ OpenAI) thay vì khóa CheapTokens;
• biến môi trường trống trong terminal này: echo ${#CHEAPTOKENS_API_KEY} in ra độ dài của nó.

Dashboard chỉ hiển thị khóa một lần. Nếu bị mất, hãy nhấn Rotate để lấy khóa mới và cập nhật nó ở mọi nơi sử dụng.

402 — số dư trống hoặc không có khóa trong yêu cầu#

API trả về 402 trong hai tình huống khác nhau:

1. Số dư đã hết. Các yêu cầu được thanh toán từ số dư; khi hết, khóa bị tạm dừng. Nạp tiền trong dashboard và các yêu cầu sẽ hoạt động trở lại.
2. Yêu cầu hoàn toàn không có khóa. Nếu thiếu header Authorization (hoặc x-api-key đối với client theo phong cách Anthropic), API trả về 402 với type insufficient_funds. Hãy kiểm tra rằng công cụ của bạn thực sự gửi khóa: phong cách OpenAI là Authorization: Bearer <key>.

404 — sai địa chỉ#

{"error": {"message": "Invalid URL (GET /v1/chat/completion)", "type": "invalid_request_error", "param": null, "code": null}}

Đường dẫn bị gõ sai — ở đây là completion thay vì completions. Các nguyên nhân phổ biến khác:

• Base URL thiếu /v1. Client theo phong cách OpenAI cần https://api.cheaptokens.dev/v1. Nếu không có /v1, yêu cầu sẽ trượt khỏi API và bạn nhận được trang HTML 404 thay vì JSON.
• /v1 hai lần. Một số client tự thêm /v1; khi đó base URL phải là gốc, https://api.cheaptokens.dev. Client theo phong cách Anthropic luôn dùng địa chỉ gốc.

400 — không tìm thấy model#

{"error": {"message": "Model \"deepseek-v4-flash\" not found. Available: …", "type": "invalid_request_error", "param": "model"}}

ID model phải là ID đầy đủ, bao gồm cả tiền tố trước dấu gạch chéo: deepseek-ai/DeepSeek-V4-Flash-0731, không phải deepseek-v4-flash. Chữ hoa hay chữ thường không quan trọng. Thông báo lỗi liệt kê các ID khả dụng, và danh sách đầy đủ luôn có tại GET /v1/models.

400 cũng được trả về khi phần thân yêu cầu sai định dạng — ví dụ mảng messages trống (messages field is required and must be a non-empty array) hoặc tin nhắn thiếu role.

413 — yêu cầu quá lớn#

Phần thân yêu cầu bị giới hạn ở 16 MB. Agent có thể chạm giới hạn này khi đưa các tệp hoặc log khổng lồ vào ngữ cảnh. Chỉ gửi những phần model cần và cắt bớt đầu ra dài của công cụ.

429 — quá nhiều yêu cầu#

Nếu bạn nhận 429, hãy chậm lại. Phản hồi bao gồm header Retry-After với số giây cần chờ. Các SDK OpenAI chính thức tự động thử lại (max_retries); trong mã của riêng bạn, hãy chờ Retry-After trước lần thử tiếp theo.

503 — model tạm thời không khả dụng#

Một model có thể tạm thời không khả dụng; khi đó API trả về 503 với type model_unavailable, và thẻ model trên trang hiển thị "temporarily unavailable". Hãy thử lại sau hoặc chuyển trường model sang model khác — khóa và địa chỉ giữ nguyên.

Chờ lâu và timeout#

Các model suy luận như zai-org/GLM-5.3-Flash suy nghĩ trước khi trả lời, nên token đầu tiên có thể mất một lúc. Hãy dùng streaming hoặc tăng timeout của client — ví dụ timeout=120 trong SDK OpenAI.