Đo lường & tính lặp lại (idempotency)

Bộ đo lường đơn vị là cốt lõi của sản phẩm — trang này quy định hợp đồng chính xác cho các kỳ vọng thanh toán của bạn.

Những gì được tính phí

Chỉ các yêu cầu thành công (2xx) tới các endpoint dữ liệu /v1/{domain}/* mới tiêu tốn đơn vị. Các endpoint cốt lõi (/v1/usage, /v1/me, quản lý webhook, /v1/meta/*) luôn miễn phí và không tính phí. Các yêu cầu xác thực thất bại (401/403) và từ chối do quá giới hạn (429) không bao giờ bị tính phí.

Chi phí đơn vị

Chi phí	Áp dụng cho
1 đơn vị	Mặc định — hầu hết thao tác đọc GET /v1/legal/* (văn bản, hiệu lực, quan hệ, thay đổi, search chế độ mode=fts)
2 đơn vị	GET /v1/legal/search với mode=semantic hoặc mode=hybrid (gói Builder trở lên)
100 đơn vị	GET /v1/legal/export (gói Pro)
0 đơn vị	Gửi lại lặp lại (idempotent replays)

Chi phí được khai báo theo từng route và trả về trên mọi yêu cầu tính phí thành công qua header X-CrawlPipe-Units-Charged, cùng với X-CrawlPipe-Units-Remaining cho chu kỳ thanh toán hiện tại.

Tính lặp lại (Idempotency)

Gửi header Idempotency-Key: <uuid> trên bất kỳ yêu cầu nào. Trong cửa sổ 24 giờ:

• Cùng key + cùng yêu cầu (tham số/nội dung giống hệt) → phản hồi được bộ nhớ đệm phát lại nguyên văn, meta.units_charged là 0, và meta.idempotent_replay: true được thiết lập. An toàn để thử lại sau khi bị timeout mà không lo bị tính phí hai lần.
• Cùng key + yêu cầu khác → lỗi 409 idempotency_conflict. Việc dùng lại key cho yêu cầu khác là lỗi từ phía gọi API, không phải thử lại.

Đây là cơ chế giúp các vòng lặp thử lại của AI agent an toàn: agent không biết cuộc gọi trước đó có thành công hay không có thể luôn thử lại với cùng Idempotency-Key và chỉ bị tính phí tối đa một lần.

Hạn mức (Quotas)

Các gói bao gồm hạn mức đơn vị cố định hàng tháng (plan.included_units — xem Bảng giá). Không có phí vượt hạn mức ở v1: khi hết hạn mức, các yêu cầu sẽ nhận 429 quota_exceeded cho đến khi sang chu kỳ mới hoặc bạn nâng cấp gói. Tổ chức của bạn sẽ nhận email thông báo khi dùng đạt 80% hạn mức, mỗi chu kỳ một lần.

Giới hạn tần suất (Rate limits)

Độc lập với hạn mức đơn vị, mỗi gói còn có giới hạn số yêu cầu/phút trong cửa sổ 1 phút. Vượt quá giới hạn sẽ trả về 429 rate_limited kèm header Retry-After — điều này không tiêu tốn đơn vị.