Khắc Phục Sự Cố — Tài liệu TokSpan

Mã Lỗi Thường Gặp

Mã	Thông Báo	Nguyên Nhân	Cách Khắc Phục
401	Khóa API không hợp lệ	Khóa bị thiếu, sai định dạng hoặc đã bị thu hồi	Kiểm tra header `Authorization: Bearer sk-...`. Xác minh khóa đang hoạt động trong Dashboard → API Keys. Khóa bắt đầu bằng `sk-`.
402	Số dư không đủ	Số dư tài khoản bằng 0 hoặc âm	Thêm credit trong Dashboard → Billing. Bật tự động nạp tiền cho khóa production.
404	Không tìm thấy mô hình	Model ID không tồn tại hoặc bị sai chính tả	Kiểm tra tên mô hình với danh sách mô hình có sẵn. Tên mô hình phân biệt chữ hoa/thường.
429	Vượt quá rate limit	Quá nhiều request hoặc token trong khoảng thời gian hiện tại	Kiểm tra header `x-ratelimit-remaining-*`. Triển khai exponential backoff. Xem Rate Limits.
500	Lỗi máy chủ nội bộ	Sự cố phía TokSpan	Thử lại với backoff. Nếu kéo dài >5 phút, kiểm tra trang trạng thái.
502	Cổng không hợp lệ	Nhà cung cấp ngược dòng gặp sự cố hoặc timeout	Thử lại — auto-failover sẽ định tuyến đến mô hình dự phòng của bạn. Nếu kéo dài, cấu hình chuỗi failover.
503	Dịch vụ không khả dụng	Quá tải tạm thời	Chờ và thử lại sau thời gian trong header `Retry-After`. Kiểm tra trang trạng thái.

Sự Cố Kết Nối

Lỗi "Connection refused" / "Name resolution failed"

Xác minh base URL: https://api.tokspan.com/v1 (lưu ý: https://, không phải http://)
Kiểm tra firewall / proxy của bạn cho phép HTTPS outbound trên cổng 443
Kiểm tra DNS: nslookup api.tokspan.com sẽ trả về một IP
Nếu bạn ở khu vực có truy cập internet bị hạn chế, bạn có thể cần tự lưu trữ

Lỗi "SSL Certificate Error"

Đảm bảo chứng chỉ CA của hệ thống được cập nhật
Kiểm tra đồng hồ hệ thống của bạn chính xác (chứng chỉ SSL phụ thuộc thời gian)
Chúng tôi dùng chứng chỉ Let's Encrypt — được tin cậy bởi mọi hệ điều hành lớn

Lỗi "Request Timeout"

Timeout mặc định khác nhau tùy SDK. Đặt rõ ràng: tối thiểu 60s cho chat, 120s cho sinh văn bản dài
Dùng streaming (stream: true) — bạn sẽ nhận token mà không cần chờ toàn bộ phản hồi
Nếu timeout xảy ra liên tục với một mô hình cụ thể, nhà cung cấp ngược dòng có thể đang chậm — thử mô hình khác hoặc thêm hậu tố -fast

Danh Sách Chẩn Đoán Nhanh

Chạy qua các bước này trước khi gửi ticket hỗ trợ:

Khóa API của bạn có hợp lệ không? — Kiểm tra bằng lệnh curl tối giản này:

curl -X POST "https://api.tokspan.com/v1/chat/completions" \
  -H "Authorization: Bearer sk-your-key" \
  -H "Content-Type: application/json" \
  -d '{"model":"gpt-4o","messages":[{"role":"user","content":"Hi"}]}'

Nếu trả về 401, vấn đề là ở khóa. Nếu trả về 200 kèm nội dung, khóa và base URL của bạn đúng.

Tên mô hình có đúng không? — Kiểm tra danh mục mô hình. Lỗi thường gặp: dùng "gpt4" thay vì "gpt-4o".
Bạn có credit không? — Kiểm tra Dashboard → Billing. Số dư phải > $0.
Bạn có đang bị rate limit không? — Kiểm tra response header cho x-ratelimit-remaining-requests. Nếu là 0, chờ khoảng thời gian reset.
Dịch vụ có đang hoạt động không? — Kiểm tra API Status Page về các sự cố đang diễn ra.

Sự Cố Riêng SDK

Python (openai SDK)

ModuleNotFoundError: openai → pip install openai
openai.APIError / APIConnectionError → Kiểm tra kết nối mạng. Thử curl trực tiếp để phân biệt lỗi SDK với lỗi mạng.
Proxy: Đặt http_client=httpx.Client(proxy="http://proxy:8080") nếu đứng sau proxy công ty

Node.js (openai SDK)

Cannot find module 'openai' → npm install openai
ERR_MODULE_NOT_FOUND → Dùng import với ESM hoặc require('openai') với CJS
fetch is not defined (Node < 18) → Nâng cấp lên Node 18+ hoặc polyfill globalThis.fetch

Vẫn Bị Kẹt?

Gửi kèm các thông tin sau khi liên hệ hỗ trợ — sẽ tăng tốc đáng kể việc giải quyết:

Email tài khoản của bạn
Request ID từ phản hồi lỗi (trường id)
Toàn bộ nội dung phản hồi lỗi và mã trạng thái HTTP
Mô hình bạn đang gọi và đoạn mã tối giản tái hiện sự cố
Phiên bản SDK của bạn (pip show openai / npm list openai)

Gửi email cho chúng tôi tại support@tokspan.com — chúng tôi phản hồi trong 24 giờ.