Xử lý lỗi finlens: FinLensError và cây ngoại lệ Python

Mọi lỗi thư viện finlens chủ động sinh ra đều nằm trong một cây thừa kế duy nhất, gốc là finlens.FinLensError. Trang này nói bạn nên bắt ở mức nào, đọc gì từ ngoại lệ bắt được, và phân biệt lỗi (dừng chương trình) với cảnh báo (không dừng).

Một dòng bắt hết

import finlens

client = finlens.client()          # đọc FINLENS_API_KEY

try:
    df = client.eod.stock.ohlcv("HPG", start="2024-01-01", end="2024-06-30")
except finlens.FinLensError as exc:
    print(exc.code, "-", exc.message)

Không cần except Exception. Bắt rộng như vậy sẽ nuốt luôn KeyboardInterrupt của bạn, lỗi gõ sai tên cột, và mọi thứ khác không liên quan đến FinLens.

Ngoại lệ mang theo những gì

Mọi lớp trong cây đều có sáu thuộc tính sau:

str(exc) gộp ba thứ quan trọng nhất lại:

[FL_QUOTA_DAILY] Đã dùng hết hạn mức 5000 request/ngày. Đặt lại lúc 2026-08-05T00:00:00+07:00. (request_id=req_8f3a1c) -> https://docs.finlens.vn/python-sdk/errors/FL_QUOTA_DAILY

try:
    df = client.eod.stock.ohlcv("HPG")
except finlens.QuotaError as exc:
    if exc.code == "FL_QUOTA_DAILY":   # đúng
        ...
    if "hạn mức" in exc.message:       # sai — sẽ hỏng khi câu chữ đổi
        ...

Một số lớp mang thêm thuộc tính riêng:

Cây ngoại lệ

FinLensError
├── ConfigurationError            cấu hình client sai: thiếu khoá, base URL hỏng
├── UnsupportedOperationError     có trong API nhưng chưa khả dụng ở bản này
│
├── AuthError                     không xác thực được khoá
│   ├── InvalidApiKeyError        khoá không tồn tại hoặc đã bị thu hồi
│   ├── ApiKeyExpiredError        khoá hết hạn
│   ├── AccountExpiredError       gói dịch vụ hết hạn (khoá vẫn còn hiệu lực)
│   └── AccountInactiveError      tài khoản inactive hoặc banned
│
├── TierError                     gói hiện tại không cho phép thao tác này
│   ├── DatasetNotInTierError     bộ dữ liệu ngoài gói
│   └── SymbolNotInTierError      mã chứng khoán ngoài gói
│
├── QuotaError                    chạm một giới hạn sử dụng
│   ├── RateLimitError            vượt giới hạn tần suất
│   └── DailyQuotaExceededError   hết hạn mức request trong ngày
│
├── ValidationError               tham số truyền vào không hợp lệ
│   ├── InvalidSymbolError        mã sai định dạng hoặc không tồn tại
│   ├── InvalidDateRangeError     khoảng thời gian sai hoặc quá dài
│   ├── InvalidIntervalError      interval không hợp lệ hoặc nhập nhằng
│   ├── CompanyTypeMismatchError  các mã thuộc nhiều loại hình doanh nghiệp
│   └── UnitMismatchError         ghép các bảng khác đơn vị
│
├── TransportError                lỗi mạng, trước khi có response hợp lệ
│   ├── ConnectionFailedError     không kết nối được
│   │   └── TlsVerificationError  không xác thực được chứng chỉ TLS
│   ├── RequestTimeoutError       hết thời gian chờ
│   └── ServerError               backend trả 5xx sau khi đã thử lại
│
├── DataError                     có response nhưng nội dung không đúng hợp đồng
│   ├── DecodingError             không giải mã được payload
│   ├── SchemaMismatchError       server trả schema client không hiểu
│   ├── NoDataError               tài nguyên không tồn tại
│   └── PartialFetchError         một phần các mã thất bại
│
├── UpgradeRequiredError          bản client này không còn được hỗ trợ
└── IncompatibleApiVersionError   client và backend khác major của hợp đồng

AuthError, TierError, QuotaError, ValidationError, TransportError và DataError vừa là lớp cha vừa là lớp bắt được: bắt lớp cha là bắt trọn nhánh, kể cả những lớp con được thêm về sau. TlsVerificationError là ví dụ — nó là lớp con của ConnectionFailedError, nên code chỉ bắt lớp cha vẫn nhận được nó mà không phải sửa gì.

Nên bắt ở mức nào

Bảng phân loại cho nhóm job định kỳ:

Hai dòng đầu giao nhau ở một chỗ: TlsVerificationError là một ConnectionFailedError. Nếu bạn bắt lớp cha để thử lại thì phải đặt nhánh TlsVerificationError lên trước, không thì một lỗi vĩnh viễn sẽ bị thử lại mãi mà không bao giờ khác đi.

import time
import finlens

client = finlens.client()

try:
    df = client.eod.stock.investor.flow("HPG", start="2024-01-01")
except finlens.RateLimitError as exc:
    time.sleep(exc.retry_after or 60)
except finlens.DailyQuotaExceededError as exc:
    print("Hạn mức đặt lại lúc", exc.resets_at)
except finlens.AuthError as exc:
    print("Kiểm tra lại khoá API:", exc.message)
except finlens.FinLensError as exc:
    print(exc.code, exc.message, exc.request_id)

Thứ tự except đi từ hẹp tới rộng. Đặt FinLensError lên trên cùng thì mọi nhánh phía dưới không bao giờ chạy.

ValidationError vẫn là ValueError

ValidationError kế thừa cả FinLensError và ValueError, và đó là chủ đích: code cũ viết except ValueError quanh lời gọi FinLens vẫn tiếp tục chạy sau khi nâng lên 1.x.

try:
    df = client.eod.stock.ohlcv("HPG", interval="1M")
except ValueError as exc:          # vẫn bắt được
    print(exc)

Nhưng khi viết mới thì bắt finlens.ValidationError: nó chỉ bắt lỗi tham số của FinLens, không nuốt luôn ValueError từ code khác của bạn.

Ba lỗi tham số hay gặp nhất:

• InvalidIntervalError — interval chỉ nhận 1d, 1w, 1mo, 3mo, 6mo, 1y. 1M và 1m bị từ chối thẳng thay vì đoán ý: trong từ vựng cũ hai token đó chỉ khác nhau ở chữ hoa nhưng lệch nhau 43.200 lần.
• InvalidDateRangeError — khoảng thời gian vượt giới hạn. Giới hạn thật do server quyết định, đọc bằng client.limits(), không phải hằng số trong thư viện.
• CompanyTypeMismatchError — các mã thuộc nhiều loại hình doanh nghiệp khác nhau (phi tài chính, ngân hàng, chứng khoán, bảo hiểm). Cây chỉ tiêu báo cáo tài chính của chúng khác nhau nên không gộp vào một bảng được.

Nhiều mã trong một lời gọi: on_error

Khi bạn xin 50 mã và 1 mã hỏng, 49 mã còn lại không được mất theo. Đó là việc của tham số on_error, có ở mọi hàm nhận nhiều mã.

Cả ba trường hợp đều ghi lại chi tiết vào df.attrs["finlens"]:

df = client.eod.stock.ohlcv(ma_list, start="2024-01-01")   # on_error="warn"

if df.attrs["finlens"]["partial"]:
    for symbol, ly_do in df.attrs["finlens"]["failed"].items():
        print(symbol, ly_do["code"], ly_do["message"])

Với on_error="raise", dữ liệu đi kèm ngoại lệ nên bạn không phải gọi lại từ đầu:

try:
    df = client.eod.stock.ohlcv(ma_list, on_error="raise")
except finlens.PartialFetchError as exc:
    df = exc.data                    # 49 mã thành công, vẫn dùng được
    print(exc.failures)              # {"XYZ": InvalidSymbolError(...)}

exc.failures ánh xạ mã chứng khoán → ngoại lệ tương ứng, nên mỗi mã hỏng vẫn giữ đủ .code và .message của riêng nó.

Kết quả không có dòng nào không phải lỗi. Một khoảng ngày nghỉ, hay một mã mới niêm yết, trả về DataFrame rỗng với đúng cột và đúng dtype — không cảnh báo, không ngoại lệ. NoDataError chỉ dành cho trường hợp server báo rõ rằng tài nguyên không tồn tại.

TlsVerificationError: máy bạn nằm sau proxy kiểm tra TLS

Rất phổ biến trong mạng doanh nghiệp: proxy kiểm tra TLS hoặc phần mềm diệt virus chèn vào giữa kết nối bằng một CA riêng, mà bundle chứng chỉ mặc định của Python không có CA đó.

Đây là lỗi vĩnh viễn, khác hẳn một lỗi kết nối thường: thử lại không bao giờ cứu được, và cách sửa nằm ở máy bạn chứ không ở phía FinLens. Vì vậy thư viện không thử lại nó.

client = finlens.client(ca_bundle="/duong/dan/toi/ca-bundle.pem")

Hoặc đặt biến môi trường một lần cho cả máy:

# Linux / macOS
export FINLENS_CA_BUNDLE="/duong/dan/toi/ca-bundle.pem"

# Windows PowerShell
$env:FINLENS_CA_BUNDLE = "C:\certs\ca-bundle.pem"

File CA bundle do bộ phận IT của bạn cấp — đó là chứng chỉ gốc của chính proxy đang đứng giữa.

SchemaMismatchError: response sai hình dạng

Ném ra khi server trả về một cấu trúc mà phiên bản client này không hiểu. Hai nguyên nhân, theo thứ tự khả năng:

1. FINLENS_BASE_URL đang trỏ nhầm chỗ — thường là một endpoint cũ hoặc một backend cục bộ đang chạy phiên bản khác. Kiểm biến môi trường trước tiên.
2. Client quá cũ so với backend. Nâng cấp bằng pip install -U finlens.

Bảng tra mã lỗi

Ánh xạ là nhiều-đối-một: nhiều mã có thể trỏ về cùng một lớp. Bắt theo lớp, phân biệt theo mã.

Dấu ... là chỗ thông báo thật điền giá trị cụ thể của lời gọi.

Một mã không có trong bảng này vẫn được ánh xạ về một lớp trong cây theo nhóm của nó — không bao giờ thành một RuntimeError trần. Đó là lý do except finlens.FinLensError giữ được lời hứa của mình kể cả khi backend thêm mã mới.

Cảnh báo khác lỗi

Cảnh báo không dừng chương trình. Chúng đi qua module warnings của Python, nên bạn tắt hay bật từng loại một cách chọn lọc.

FinLensWarning (UserWarning)
├── UpgradeAvailableWarning   có bản client mới hơn trên PyPI
├── QuotaLowWarning           hạn mức sắp cạn. Chỉ phát một lần mỗi client
├── PartialDataWarning        một phần các mã thất bại, với on_error="warn"
├── DataQualityWarning        dữ liệu trả về có vấn đề đã biết
└── TierLimitWarning          yêu cầu đã bị cắt bớt cho vừa gói dịch vụ

FinLensDeprecationWarning (DeprecationWarning)
    một phần của API công khai sắp bị gỡ bỏ

Tắt một loại, giữ nguyên các loại còn lại:

import warnings
import finlens

warnings.filterwarnings("ignore", category=finlens.QuotaLowWarning)

Hoặc làm ngược lại — biến cảnh báo thành lỗi để nó không thể bị bỏ qua. Hữu ích trong job chạy tự động, nơi không ai đọc stderr:

warnings.filterwarnings("error", category=finlens.PartialDataWarning)

Lúc đó PartialDataWarning sẽ được ném ra như một ngoại lệ và dừng chương trình — khác với on_error="raise" ở chỗ bạn không nhận được .data.

Tắt toàn bộ cảnh báo của FinLens mà không đụng tới cảnh báo của thư viện khác:

warnings.filterwarnings("ignore", category=finlens.FinLensWarning)

Khi cần báo lỗi

Gửi kèm ba thứ, chúng cắt ngắn phần lớn cuộc trao đổi qua lại:

import finlens

print(finlens.__version__)
print(finlens.build_info())     # commit và thời điểm build của binary bạn đang chạy

Cộng thêm exc.request_id của lời gọi hỏng — đó là thứ cho phép tra lại đúng request đó ở phía FinLens.

Danh sách thay đổi từng phiên bản: Nhật ký thay đổi.