Mã Lỗi — Tài liệu TokSpan

Mã Trạng Thái HTTP

Mã	Ý Nghĩa	Hành Động
400	Yêu Cầu Không Hợp Lệ	Kiểm tra nội dung yêu cầu — có thể JSON không đúng định dạng hoặc thiếu trường bắt buộc
401	Không Được Ủy Quyền	Xác minh khóa API của bạn chính xác và đang hoạt động trong bảng điều khiển
404	URL Không Hợp Lệ / Không Tìm Thấy Endpoint	Kiểm tra đường dẫn yêu cầu theo tài liệu tham khảo API
429	Vượt Giới Hạn Tốc Độ / Hạn Mức Không Đủ	Với giới hạn tốc độ, triển khai exponential backoff với jitter. Nếu 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 bảng điều khiển thay vì thử lại — xem giới hạn tốc độ
500	Lỗi Nội Bộ	Lỗi phía TokSpan — thử lại với backoff hoặc liên hệ hỗ trợ
502	Cổng Không Hợp Lệ	Lỗi từ nhà cung cấp ngược dòng — tự động chuyển đổi dự phòng có thể được kích hoạt
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 — thử lại với backoff. Nếu lỗi kèm mã `model_not_found`, mô hình không khả dụng cho khóa của bạn — hãy kiểm tra tên mô hình trong danh mục mô hình

Định Dạng Phản Hồi Lỗi

Lỗi được trả về trong một đối tượng error chứa message dễ đọc và định danh type. Trên TokSpan, type thường là new_api_error, và lỗi số dư tài khoản kèm code: "insufficient_user_quota". Ví dụ:

json
{
  "error": {
    "message": "You can access all models, but this request exceeded your account balance. Please top up at the Dashboard.",
    "type": "new_api_error",
    "param": null,
    "code": "insufficient_user_quota"
  }
}

Đọc thông báo rất quan trọng. 429 với thông báo giới hạn tốc độ nghĩa là lùi lại và thử lại; 429 (hoặc 400) với thông báo hạn mức nghĩa là nạp credit trước. Hãy đọc thông báo trước khi quyết định phản ứng. Văn bản thông báo ở đây chỉ mang tính minh họa — luôn dựa vào mã trạng thái HTTP và trường code.