Giới hạn

10 phút đọc

Ferry API kiểm soát tần suất gọi lệnh theo địa chỉ IP xuất phát của hệ thống đối tác nhằm bảo vệ tính ổn định toàn hệ thống. Trang này mô tả mức giới hạn áp dụng toàn cục, các ngoại lệ được siết chặt tại bước xác nhận xuất vé, và các giới hạn kỹ thuật khác mà đối tác cần xử lý.

Giới hạn tần suất toàn cục được tính theo địa chỉ IP nguồn: 50 lệnh gọi trong mỗi 100 mili-giây (tương đương khoảng 500 lệnh/giây), không tính theo từng khoá API.
Hai đối tác đi chung một địa chỉ IP công cộng sẽ dùng chung hạn mức; một đối tác đi ra từ nhiều IP độc lập sẽ có hạn mức nhân theo số IP.
Bước xác nhận xuất vé có hai lớp giới hạn chặt: giới hạn cứng 5 lệnh/60 giây theo IP (trả 429) và giới hạn mềm 5 lần/60 giây theo từng booking (trả lỗi nghiệp vụ).
Khi vượt giới hạn (HTTP 429), đối tác cần áp dụng cơ chế thử lại có khoảng lùi tăng dần ngẫu nhiên (exponential backoff with jitter).
Các giới hạn phụ cần lưu ý: độ lớn gói tin tối đa 1 MB, số bản ghi phân trang bị kẹp tối đa 50–100 bản ghi, và hạn chờ tiếp nhận webhook 2.000 ms.

Giới hạn toàn cục

Ferry áp dụng cấu hình giới hạn tần suất chung cho toàn bộ API công khai: 50 lệnh gọi trong mỗi 100 mili-giây, đếm theo địa chỉ IP nguồn.

Đơn vị thời gian tính bằng mili-giây (100 ms tương đương 1/10 giây). Do đó, mức 50 lệnh/100 ms tương đương thông lượng xử lý lên tới khoảng 500 lệnh/giây.

Mức trần này được thiết lập để ngăn chặn các đợt bùng nổ lưu lượng hoặc tấn công từ chối dịch vụ thô. Một hệ thống tích hợp đặt vé hoạt động bình thường hiếm khi chạm đến ngưỡng giới hạn này.

Sơ đồ dưới đây cho thấy đường đi của một lệnh gọi qua các tầng giới hạn tốc độ và kết quả nhận được:

flowchart TB
    CALL["Một lệnh gọi từ hệ thống của bạn"]
    IP{"Lớp 1 — đếm theo địa chỉ IP<br/>50 lệnh trong mỗi 100 mili-giây"}
    OVER{"Lớp 2 — bước xác nhận xuất vé?<br/>5 lệnh trong mỗi 60 giây"}
    LOCK{"Lớp 3 — khoá xuất vé theo booking<br/>còn hiệu lực 600 giây"}
    SOFT{"Lớp 4 — giới hạn mềm xuất vé<br/>5 lần trong mỗi 60 giây"}
    OK["Ferry xử lý bình thường"]
    E429["Nhận 429<br/>gọi lại theo khoảng lùi tăng dần"]
    LOCKED["Nhận lỗi nghiệp vụ 120100<br/>chờ ít nhất 60 giây rồi gọi lại"]
    SOFTED["Nhận lỗi nghiệp vụ<br/>không phải 429"]

    CALL --> IP
    IP -->|"vượt trần IP"| E429
    IP -->|"trong trần"| OVER
    OVER -->|"không phải bước xác nhận"| OK
    OVER -->|"là bước xác nhận, vượt 5 lệnh trong 60 giây"| E429
    OVER -->|"là bước xác nhận, trong trần"| LOCK
    LOCK -->|"booking đang có tiến trình xuất vé khác"| LOCKED
    LOCK -->|"booking rảnh"| SOFT
    SOFT -->|"vượt 5 lần trong 60 giây"| SOFTED
    SOFT -->|"trong trần"| OK

Hành vi khi vượt trần

Khi vượt ngưỡng, hệ thống trả về mã trạng thái HTTP 429 (Too Many Requests) kèm mốc thời gian và đường dẫn gọi API.

Hai lưu ý quan trọng:

Không có thông điệp tuỳ biến: Thân phản hồi 429 trả về thông báo lỗi chuẩn từ thư viện bảo vệ. Bộ xử lý lỗi không nên tìm kiếm chuỗi văn bản tiếng Việt cụ thể trong thân phản hồi này.
Ferry không ghi log mức lỗi cho mã 429: Tầng lọc lỗi chỉ ghi nhận sự cố từ mã 500 trở lên. Hệ thống Ferry không tự động phát hiện đối tác đang bị chặn tần suất; việc theo dõi tỷ lệ lỗi 429 hoàn toàn thuộc về trách nhiệm giám sát của đối tác.

Chiến lược thử lại khuyến nghị: khi nhận mã 429, áp dụng thuật toán lùi tăng dần có yếu tố ngẫu nhiên (bắt đầu từ 1 giây, nhân đôi sau mỗi lần thử, chặn trần 30 giây, tối đa 5 lần).

Toàn bộ hệ thống đếm tần suất dựa trên địa chỉ IP nguồn gửi yêu cầu tới:

Hai đối tác dùng chung một địa chỉ IP công cộng sẽ dùng chung hạn mức: Lưu lượng của đối tác khác có thể khiến bạn bị chặn 429, và ngược lại.
Một đối tác đi ra từ nhiều địa chỉ IP thì hạn mức nhân lên: Nếu cùng một ứng dụng tích hợp chạy trên nhiều máy chủ có địa chỉ IP ra Internet khác nhau, mỗi địa chỉ sẽ sở hữu một hạn mức 500 req/s độc lập.

Bạn không nên thiết kế hệ thống dựa trên giả định có hạn mức riêng biệt cho từng khoá API. Nếu hệ thống của bạn đi qua proxy hoặc địa chỉ IP dùng chung, hãy liên hệ Ferry để thống nhất phương án xử lý.

Ngoại lệ theo nhóm

Phần lớn các API sử dụng mức giới hạn toàn cục. Ba nhóm thao tác sau đây có quy định riêng:

Nhóm lệnh gọi	Giới hạn áp dụng	Cơ chế đếm	Ý nghĩa thực tế
Toàn hệ thống (mặc định)	50 lệnh / 100 mili-giây	Theo địa chỉ IP	Áp dụng cho tra cứu, tạo đơn, quản lý chung
Bước xác nhận xuất vé	5 lệnh / 60 giây	Theo địa chỉ IP	Siết chặt để bảo vệ kết nối với cổng hãng tàu
Tra cứu booking công khai	60 lệnh / 60 giây	Theo địa chỉ IP	Dành cho trang tra cứu công khai của khách cuối
Kênh sự kiện SSE thời gian thực	Miễn giới hạn tần suất	Không áp dụng	Chỉ phục vụ phiên đăng nhập web, không mở cho API key

Phân biệt hai cơ chế giới hạn tại bước xác nhận xuất vé

Bước xác nhận xuất vé có hai cơ chế kiểm soát cùng mang con số 5 lần / 60 giây nhưng khác biệt hoàn toàn về bản chất:

Cơ chế	Căn cứ đếm	Phản hồi khi vượt ngưỡng
Giới hạn cứng tầng mạng	Địa chỉ IP của bạn	HTTP 429 kèm thông điệp chuẩn
Giới hạn mềm tầng nghiệp vụ	Từng mã booking cụ thể	Lỗi nghiệp vụ (mã sáu chữ số), không phải 429

Giới hạn mềm theo booking cho phép tối đa 5 lần xác nhận trong vòng 60 giây trên cùng một booking. Cơ chế này bảo vệ hệ thống khỏi việc người dùng bấm xác nhận liên tục trên một đơn hàng khi lệnh đầu tiên đang được xử lý.

Quy tắc thử lại:

Nhận mã 429: Chờ theo khoảng lùi tăng dần rồi gọi lại.
Nhận lỗi nghiệp vụ: Tra cứu lại trạng thái booking trước; việc gọi lại mù quáng sẽ chỉ lặp lại cùng một lỗi nghiệp vụ đó.

Những giới hạn khác bạn sẽ đụng

Ngoài giới hạn tần suất theo thời gian, đối tác cần lưu ý các trần kỹ thuật sau:

Giới hạn	Giá trị trần	Hành vi khi vượt quá
Kích thước dữ liệu gửi lên (Payload)	Tối đa 1 MB	Lệnh gọi bị từ chối ngay tại tầng biên
Số bản ghi mỗi trang phân trang	Tối đa 50 (một số API là 100)	Kẹp im lặng: hệ thống tự giới hạn về mức trần mà không báo lỗi
Khoá xuất vé theo booking	Giữ khoá 600 giây	Lệnh thứ hai gửi lên khi đang xuất vé nhận mã `120100`
Khoá thanh toán theo booking	Giữ khoá 180 giây, độc lập với khoá xuất vé	Lệnh thanh toán đồng thời nhận mã `120100`
Mã xác thực email	5 lần / 15 phút cho một email	Lần thứ 6 trở đi bị từ chối
Hạn chờ webhook gửi ra	2.000 mili-giây	Điểm nhận của bạn chậm hơn 2 giây là mất sự kiện vĩnh viễn

Hai điểm cần lưu ý đặc biệt:

Kẹp phân trang im lặng: Yêu cầu lấy 200 bản ghi nhưng chỉ nhận về 50 bản ghi là hành vi bình thường. Đối tác không được kết luận “hết dữ liệu” khi nhận ít bản ghi hơn số lượng yêu cầu mà phải kiểm tra con trỏ phân trang tiếp theo.
Hạn chờ webhook là ràng buộc phía bạn: Điểm tiếp nhận webhook của bạn bắt buộc phải trả lời trong vòng 2 giây. Hãy áp dụng mô hình nhận sự kiện vào hàng đợi và phản hồi 200 ngay lập tức.

Khi bị chặn thì làm gì

Năm bước xử lý theo thứ tự:

Giảm số tiến trình phát lệnh thay vì tăng luồng: Giới hạn đếm theo địa chỉ IP nguồn, tăng thêm luồng gọi chỉ khiến bộ đếm đầy nhanh hơn và kéo dài thời gian bị chặn.
Áp dụng khoảng lùi tăng dần ngẫu nhiên (jitter): Thêm một khoảng ngẫu nhiên vào thời gian chờ để tránh việc nhiều luồng cùng gọi lại tại một thời điểm.
Tách biệt hàng đợi đọc và ghi: Không để các lệnh tra cứu chuyến hàng loạt chiếm dụng hạn mức của bước xác nhận xuất vé — nơi chỉ cho phép 5 lệnh/60 giây.
Lưu nhật ký mã truy vết (trace ID): Ghi lại thời điểm, mã truy vết và địa chỉ IP của mỗi lần bị trả mã 429 để làm căn cứ đối chiếu.
Liên hệ Ferry nếu dùng chung IP công cộng: Nếu hệ thống bị chặn thường xuyên dù lưu lượng gọi thực tế thấp, khả năng cao bạn đang chia sẻ địa chỉ IP ra ngoài với một đối tác khác.

Sai lầm thường gặp

Hiểu nhầm	Thực tế	Hệ quả
Hạn mức cấp riêng cho từng khoá API	Bộ đếm tính theo địa chỉ IP	Hai đối tác sau cùng một NAT IP chặn lẫn nhau
Mức 50 lệnh mỗi 100 giây	Đơn vị là mili-giây (~500 lệnh/giây)	Thiết kế hàng đợi quá chậm không cần thiết
Vượt giới hạn luôn trả về mã 429	Giới hạn mềm theo booking trả lỗi nghiệp vụ	Bộ thử lại bỏ sót nhánh lỗi nghiệp vụ
Ferry sẽ cảnh báo khi bị chặn 429	Hệ thống không ghi log lỗi cho mã 429	Bị chặn nhiều giờ mà không bên nào phát hiện
Bị chặn thì tăng luồng gọi để bù	Tăng luồng khiến bộ đếm IP đầy nhanh hơn	Thời gian bị chặn kéo dài hơn
Nhận ít bản ghi hơn yêu cầu là lỗi	Hệ thống kẹp im lặng tối đa 50-100 bản ghi	Dừng phân trang sớm và bỏ sót dữ liệu
Webhook đến muộn là do Ferry gửi chậm	Hạn chờ 2 giây tính tại điểm nhận của bạn	Sửa sai phía, sự kiện vẫn bị rơi mất

Tra ở đâu trên Scalar

Trang này không tương ứng với một nhóm riêng trên giao diện tra cứu API tại https://api.ferry.vn/docs vì giới hạn tốc độ không được hiển thị trên Scalar:

Mục tiêu đối chiếu	Nhóm trên giao diện API
Bước xác nhận xuất vé (nơi bị siết 5 lệnh / 60 giây)	`Bookings`
Nhóm ghi dữ liệu lớn (chịu trần 1 MB payload)	`Bookings`, `Transactions`
Nhóm chỉ đọc dùng chung mức toàn cục	`Voyages`, `Organizations`, `Customers`

Đọc tiếp

Trang	Đọc khi nào
Lỗi và cách xử lý	Cần tra cứu chi tiết mã lỗi 429 và các mã nghiệp vụ
Quy ước chung	Hiểu cơ chế phân trang bằng con trỏ và quy tắc kẹp bản ghi
Đặt vé: vòng đời một booking	Thiết kế luồng đặt vé an toàn với các chặng bị siết tần suất
Xuất vé và đơn hàng	Nắm vững cơ chế khoá và giới hạn mềm khi xuất vé
Webhooks	Thiết kế điểm nhận sự kiện phản hồi dưới 2.000 ms
Trước khi chạy thật	Đưa việc giám sát mã 429 vào danh sách kiểm tra nghiệm thu

Điểm chưa xác định

Cam kết dịch vụ về hạn mức: Mức 50 lệnh trong 100 ms là ngưỡng kỹ thuật mặc định, không cấu thành cam kết chất lượng dịch vụ (SLA). Ferry có thể điều chỉnh ngưỡng này tuỳ theo tình trạng tải của hệ thống.
Header thông báo thời gian chờ: Hiện chưa có thông tin chính thức về việc bộ đếm có trả về tiêu đề Retry-After trong mọi phản hồi 429 hay không; ứng dụng phía bạn cần tự quản lý khoảng lùi chờ an toàn.