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/xu-ly-loi

Phần sau dấu -> là exc.doc_url, và nó là một hằng số: mọi mã lỗi đều dẫn về trang này. Đừng viết code ghép exc.code vào cuối exc.doc_url để dựng một liên kết theo mã — thứ dựng ra sẽ không tồn tại. Muốn đưa người dùng tới đúng mục thì in kèm exc.code và để họ tra trong bảng dưới.

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
│   ├── AmbiguousFundError        mã quỹ trùng tên ở nhiều tổ chức
│   ├── 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               khoảng bạn hỏi không có dòng nào
│   └── PartialFetchError         một phần các mã thất bại
│
├── NotFoundError                 định danh bạn đưa vào không có ở đó
│
├── IndicatorError                TA-Lib từ chối tính một chỉ báo kỹ thuật
│
├── 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ì.

try:
    df = client.watchlist.symbols(danh_muc_id)
except finlens.NoDataError:
    df = pd.DataFrame()              # đúng cho "danh mục chưa có mã nào"
except finlens.NotFoundError:
    raise                            # sai id — phải nổ, không được nuốt

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õ bằng mã FL_DATA_EMPTY rằng nó không có dữ liệu cho tài nguyên này. Còn khi chính định danh bạn đưa vào không tồn tại thì đó là NotFoundError (FL_NOT_FOUND), một lớp khác hẳn.

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.

IndicatorError và bốn mã FL_TA*

Chỉ báo kỹ thuật chạy hoàn toàn trên máy bạn và không đụng tới một response nào, nên nó không nằm dưới DataError — vốn được định nghĩa là "nhận được response nhưng nội dung không đúng hợp đồng". IndicatorError vì vậy là con trực tiếp của FinLensError.

Bốn mã chia làm hai nhóm theo ai sửa được:

Hai mã đầu là ValidationError, nên chúng cũng là ValueError và except ValueError sẵn có của bạn vẫn bắt được:

finlens.ta.RSI(close, timeperiod=14.5)
# ValidationError: [FL_TA_PARAM] `RSI`: tham số `timeperiod` phải là số nguyên,
# nhận 14.5. TA-Lib cắt phần thập phân trong im lặng, nên `timeperiod=14.5` sẽ
# chạy như `timeperiod=14` mà không báo gì.

df[["symbol", "date", "close"]].finlens.atr(14)
# ValidationError: [FL_TA_INPUT] `ATR` cần cột `high` nhưng frame không có.
# Frame này là `eod.ohlcv`. Các cột đang có: symbol, date, close.

finlens.ta.RSI(close, timeperiod=1)
# IndicatorError: [FL_TA] `RSI` lỗi bên trong TA-Lib: TA_RSI function failed
# with error code 2: Bad Parameter (TA_BAD_PARAM)

Việc bọc là cần thiết chứ không phải trang trí: TA-Lib ném Exception trần, nên nếu để nguyên thì thứ duy nhất bắt được nó là except Exception — và cam kết "except finlens.FinLensError là đủ" sẽ không còn đúng. Lỗi gốc luôn được giữ ở __cause__.

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ã.

Bảng chia theo nhóm — tiền tố ngay sau FL_ chính là tên nhóm, nên FL_QUOTA_RATE nằm ở Hạn mức và FL_TRANSPORT_TLS nằm ở Đường truyền và server. Mỗi nhóm là một mục trong mục lục bên phải. Dấu ... là chỗ thông báo thật điền giá trị cụ thể của lời gọi.

Cấu hình

Xác thực

Gói dịch vụ

Hạn mức

Tham số đầu vào

FL_VALIDATION_FUND_AMBIGUOUS là mã duy nhất mà lối thoát nằm trong .detail: detail["organization_ids"] chứa các organization_id bạn phải chọn một, và không có cách nào khác tự tìm ra chúng.

Dữ liệu và tài nguyên

FL_DATA_EMPTY và FL_DATA_NO_UNDERLYING cùng cho NoDataError — bắt lớp là bắt được cả hai — nhưng chúng là hai bệnh khác nhau: mã đầu nói khoảng bạn hỏi không có dòng nào, mã sau nói hợp đồng này không có chuỗi chỉ số cơ sở trong dữ liệu, tức không đổi khoảng nào cứu được. FL_NOT_FOUND thì cho một lớp khác hẳn — xem cây ngoại lệ.

Chỉ báo kỹ thuật

Đường truyền và server

Ba mã cuối cùng cho ra ServerError nhưng nói ba chuyện khác nhau, và bạn nên đọc .code để biết có nên thử lại không. FL_SERVICE_UNAVAILABLE là 503 kèm Retry-After: hạ tầng tạm thời không sẵn sàng, thử lại là đúng. FL_TRANSPORT_SERVER là do chính client dựng lên khi circuit breaker mở — nó chưa gửi request nào đi cả. FL_SERVER là 500, một lỗi không xác định.

Phiên bản

Mã không có trong bảng

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 HTTP status của response — 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.