Xử lý lỗi

Các lỗi mà vnstock thế hệ 6 trả ra đều kế thừa vnstock.errors.VnstockError. Mỗi lỗi có code (mã ổn định để so khớp), message, action (cách xử lý) và retryable (có nên thử lại hay không).

Python

from vnstock import Market, errors

try:
    df = Market("<nguồn>").equity("FPT").ohlcv(start="2026-10-01")
except errors.CredentialError as exc:
    print(exc.action)              # cách thêm khoá
except errors.VnstockError as exc:
    print(exc.code, exc.message)

So khớp bằng code hoặc lớp lỗi, không so khớp câu chữ của message.

Gặp lỗi về khoá, phiên hay phiên bản, chạy vnstock doctor trước: lệnh này kiểm cả máy và in cách sửa từng mục.

Lớp lỗi

Lớp	Khi nào	Gọi lại được
`InputError`	Tham số sai, thiếu nguồn, thiếu mã	Không
`CredentialError`	Chưa có khoá của nguồn trên máy	Không
`AuthError`	Nguồn từ chối khoá	Không
`LoginRequiredError`, `OtpRequiredError`	Phiên của nguồn hết hạn, cần đăng nhập hoặc OTP	Không
`RateLimitError`	Nguồn đang giới hạn tần suất	Có
`ClockSkewError`	Đồng hồ máy lệch so với nguồn	Không
`NetworkError`	Hết thời gian chờ, mất kết nối, lỗi TLS	Có
`SourceError`	Nguồn lỗi hoặc trả nội dung lạ	Tuỳ mã
`UnsupportedError`	Hàm chưa có nguồn đọc được, hoặc đã ngừng	Không
`PolicyError`	Nguồn đang tạm tắt theo chính sách máy khách	Không
`EnvelopeError`, `PayloadError`	Dữ liệu nguồn gửi không đọc được theo chuẩn	Không

Cảnh báo:

CompatibilityWarning báo cách gọi thế hệ 5 đã đổi, hoặc hàm chưa có dữ liệu.
SchemaChangeWarning, lớp con của CompatibilityWarning, báo bảng trả về khác thế hệ 5 theo cách làm hỏng mã cũ hoặc đổi nghĩa con số. Thuộc tính change là mã thay đổi (SCH-A03), severity là breaking hoặc semantic. Mỗi thay đổi chỉ cảnh báo một lần; df.attrs["schema_changes"] luôn liệt kê đủ.
DataWarning mã VNSTOCK_DATA_TRUNCATED báo kết quả thiếu: việc lật trang dừng ở trần mà nguồn vẫn còn dữ liệu. Chia nhỏ khoảng thời gian rồi gọi lại; df.attrs["truncated"] ghi chi tiết.
DataWarning ở báo cáo tài chính: VNSTOCK_VAS_IDENTITY (một đẳng thức của mẫu biểu không đúng với số nguồn gửi, xem df.attrs["identities"]), VNSTOCK_VAS_UNMAPPED (nguồn gửi trường bộ chỉ tiêu chưa có, xem df.attrs["unmapped_keys"]), VNSTOCK_TAXONOMY_* (đang dùng bộ chỉ tiêu rút gọn, kèm lý do). Xem Báo cáo tài chính.

Mã lỗi thường gặp

Mã	Nghĩa	Cách sửa
`VNSTOCK_INPUT_SOURCE`	Chưa chọn nguồn	`Market("<nguồn>")`, `source="<nguồn>"`, hoặc `vnstock.sources.use(...)`
`VNSTOCK_INPUT_ROUTE`	Quy tắc nguồn không khớp hàm nào	Dùng tên như `market.equity.quote`, mẫu như `market.crypto.*`, hoặc bỏ `route`
`VNSTOCK_INPUT_PARAM`	Hàm không nhận tham số này	Xem cột "Tham số" của hàm
`VNSTOCK_INPUT_SYMBOL`	Mã trống, sai dạng, hoặc hàm cần mã	Truyền mã, ví dụ `FPT`, `VNINDEX`, `VN30F1M`
`VNSTOCK_INPUT_MISSING_ID`	Nguồn cần mã mà lời gọi nhóm không có mã	Gọi kèm mã: `Reference("<nguồn>").equity("FPT").price_limits()`, hoặc `symbol="FPT"`
`VNSTOCK_INPUT_START_DATE`, `VNSTOCK_INPUT_END_DATE`	Ngày sai dạng	`YYYY-MM-DD`
`VNSTOCK_INPUT_DATE_RANGE`	`end` đứng trước `start`	Đổi lại thứ tự
`VNSTOCK_INPUT_INTERVAL`	Khung thời gian không hợp lệ	`1m 3m 5m 15m 30m 1H 4H 1D 1W 1M`; mỗi nguồn hỗ trợ một phần
`VNSTOCK_INPUT_LENGTH`	`length` không phải số nến hay khoảng thời gian	`length=100` hoặc `length="3M"`
`VNSTOCK_INPUT_NAMES`	`compat` không phải `v5` hay `v6`	Dùng một trong hai
`VNSTOCK_INPUT_REPORT_PERIOD`	Kỳ báo cáo không phải năm hay quý	`period="year"`, `period="quarter"`, hoặc bỏ trống để lấy cả hai
`VNSTOCK_INPUT_COMPANY_TYPE`	`company_type` không khớp mẫu biểu nguồn trả	Bỏ `company_type`, hoặc dùng loại hình ghi trong thông báo
`VNSTOCK_INPUT_TABLE_FORMAT`	`format` của báo cáo tài chính không hợp lệ	`long`, `wide` hoặc `time_series`
`VNSTOCK_VAS_TEMPLATE_UNSUPPORTED`	Mẫu biểu báo cáo tài chính chưa có cây chỉ tiêu	Lấy dữ liệu thô bằng `vnstock_oapi`
`VNSTOCK_ROUTE_UNSUPPORTED`	Nguồn này chưa có dữ liệu cho hàm	Đổi `source=` sang nguồn ghi trong thông báo
`VNSTOCK_ROUTE_REMOVED`	Hàm đã ngừng từ thế hệ 5	Dùng lời gọi thay thế ghi trong thông báo
`VNSTOCK_CREDENTIAL_MISSING`	Máy chưa có khoá của nguồn	`vnstock-oapi keys set <nguồn>`; `vnstock keys` xem nguồn nào đã có khoá
`VNSTOCK_SOURCE_AUTH`	Nguồn từ chối khoá	`vnstock-oapi check`; tạo lại khoá nếu cần
`VNSTOCK_SOURCE_OTP`	Phiên cần OTP hoặc mật khẩu mới	`vnstock-oapi auth <nguồn>`
`VNSTOCK_SOURCE_RATE_LIMITED`	Nguồn giới hạn tần suất	Chờ rồi gọi lại; giảm số mã mỗi lần
`VNSTOCK_SOURCE_UNAVAILABLE`	Nguồn đang lỗi hoặc ngoài giờ phục vụ	Gọi lại sau
`VNSTOCK_SOURCE_DISABLED`	Nguồn tạm tắt theo chính sách máy khách	Xem lý do trong thông báo; `vnstock.account.policy()`
`VNSTOCK_PAYLOAD_PRICE_UNIT`	Giá ngoài dải hợp lý của đơn vị	Báo lỗi kèm `df.attrs` hoặc thông báo lỗi
`VNSTOCK_PAYLOAD_SHAPE`	Nguồn gửi dữ liệu khác dạng mong đợi	Báo lỗi; nguồn có thể vừa đổi định dạng
`VNSTOCK_RELEASE_EXPIRED`	Bản vnstock đã hết hạn dùng	`vnstock update`, hoặc lệnh cài trong thông báo

Khi thiếu khoá hoặc khoá bị từ chối, vnstock báo lỗi ngay và không chuyển sang nguồn dự phòng. Hãy sửa khoá rồi gọi lại. Xem Chọn nguồn.

Lỗi ở dòng lệnh khi cất khoá

Lỗi	Nghĩa	Cách sửa
`NoKeyringError` khi chạy `vnstock-oapi keys set`	Máy không có keyring (GitHub Codespaces, Docker, máy chủ Linux, WSL). Khoá chưa được cất	Đặt khoá bằng biến môi trường hoặc tệp `.env` riêng tư. Nguồn có phiên thì đặt thêm `VNSTOCK_OAPI_SESSION_BACKEND=file`. Xem Máy không có keyring
`CredentialError: Chưa có khoá` khi chạy `vnstock-oapi auth`	Nguồn có phiên nhưng máy chưa có khoá	Thêm khoá trước, rồi chạy lại `auth`
`auth` báo "không cần phiên" nhưng gọi dữ liệu vẫn thiếu khoá	Nguồn không có phiên (xem `vnstock keys`), nên `auth` không kiểm khoá	`vnstock-oapi check <nguồn>`

Mục lục

Lớp lỗi

Mã lỗi thường gặp

Lỗi ở dòng lệnh khi cất khoá

Tags