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-`.
404	Không tìm thấy endpoint	URL yêu cầu không khớp với bất kỳ endpoint API nào	Kiểm tra đường dẫn yêu cầu theo tài liệu tham khảo API. Lưu ý: lỗi không tìm thấy mô hình được trả về dưới dạng `503` với mã `model_not_found` — xem Mã Lỗi.
429	Vượt quá rate limit / không đủ hạn mức	Quá nhiều request trong khoảng thời gian hiện tại, hoặc số dư tài khoản/khóa API đã cạn	Với rate limit, triển khai exponential backoff kèm jitter. Nếu thông báo lỗi nhắc đến hạn mức hoặc số dư (ví dụ `insufficient_user_quota`), hãy nạp tiền trong Dashboard → Billing thay vì thử lại. 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 nhà cung cấp dự phòng phục vụ cùng mô hình. Nếu kéo dài, liên hệ hỗ trợ.
503	Dịch vụ không khả dụng / không tìm thấy mô hình	Quá tải tạm thời, hoặc mô hình không khả dụng cho khóa của bạn	Thử lại với backoff — đừng phụ thuộc vào header `Retry-After`. Nếu lỗi kèm mã `model_not_found`, hãy kiểm tra tên mô hình trong danh mục mô hình; tên phân biệt hoa/thường. 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

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 — hãy thử một mô hình nhanh hơn hoặc nhẹ hơn

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":"MODEL_NAME","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 hoặc hết hạn mức không? — Nếu nhận phản hồi 429, hãy giảm mức đồng thời và thử lại với exponential backoff (dùng header Retry-After nếu có). Nếu lỗi nhắc đến hạn mức/số dư, hãy kiểm tra credit trong Dashboard → Billing.
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ờ.