Những gì không bị tính phí: mã lỗi và quy tắc tính phí

BlockVectra đo mức sử dụng yêu cầu bằng Compute Units (CU). Các lệnh gọi JSON-RPC và Data API chỉ bị tính phí sau khi nhận được phản hồi. Hướng dẫn này tóm tắt quy tắc xác định tính phí theo mã trạng thái HTTP, lệnh gọi JSON-RPC và Data API, cùng cách xử lý được khuyến nghị cho nhà phát triển.

Mã trạng thái HTTP và quy tắc tính phí

Quy tắc xác định tính phí và xử lý phản hồi ở cấp HTTP như sau:

Lưu ý: Khi truy cập qua Cloudflare, Cloudflare có thể trả về trang lỗi 52x hoặc 1015; những trang này không do dịch vụ tạo ra.

Header phản hồi về phí và số dư: Khi gửi x-bv-meter: 1 trong yêu cầu HTTP (áp dụng cho cả JSON-RPC và Data API), phản hồi có ít nhất một lệnh gọi bị tính phí trả về x-bv-cu-charged (Compute Units được tính phí cho yêu cầu này, hoặc tổng của các lệnh gọi bị tính phí trong batch) và x-bv-balance-units (số đơn vị số dư còn lại của tài khoản ngay sau khi tính phí, âm khi chi vượt số dư; không có nếu không biết số dư). Yêu cầu không có x-bv-meter: 1, phản hồi không tính phí lệnh gọi nào và phản hồi lỗi 402, 403, 429 hoặc 503 không có cả hai header. Script trình duyệt có thể truy cập các header phản hồi này qua CORS, còn WebSocket không dùng chúng. Số dư trừ tổng mức sử dụng chưa quyết toán được làm tròn lên một lần thành đơn vị nguyên; quyết toán hàng giờ làm tròn xuống, nên số dư báo cáo có thể tăng tối đa một đơn vị sau quyết toán.

Mã lỗi JSON-RPC và quy tắc tính phí

Cùng một mã lỗi có thể phát sinh từ nền tảng hoặc node, và cách tính phí khác nhau:

• Lỗi do chính nền tảng tạo ra: không bao giờ tính phí;
• Lỗi do node trả về: được chuyển tiếp nguyên trạng và tính phí theo trọng số phương thức, chỉ ngoại trừ các mã lỗi node được liệt kê bên dưới.

Chi tiết quy tắc

• Lỗi node không bị tính phí: Các mã -32002 (batch hết thời gian chờ), -32003 (phản hồi batch quá lớn) và -32600 (toàn bộ batch bị từ chối) của node cho biết node đã bỏ lệnh gọi sớm; các lỗi này và mọi thông báo trong cùng batch đều không bị tính phí. Mã -32601 (phương thức được công bố nhưng chưa được triển khai) và -32603 (lỗi nội bộ node) của node không bị tính phí qua HTTP hoặc WebSocket và không ảnh hưởng đến các lệnh gọi hoặc thông báo khác trong batch. Ngoài ra, 4444 (khối đã bị cắt tỉa) và -32000 (trạng thái lịch sử nằm ngoài cửa sổ lịch sử trạng thái của node, được xác định bởi state_window_blocks trong GET /v1/chains) không bị tính phí và không ảnh hưởng đến các lệnh gọi khác trong batch.
• Lỗi node bị tính phí: Các lỗi khác do node trả về được tính phí theo trọng số phương thức khi báo cáo kết quả của chuỗi, chẳng hạn execution reverted (-32000 hoặc 3 kèm data), hay lỗi -32602 invalid argument của chính node.
• Kiểm tra số dư và đồng bộ: -32020 cho biết số dư tài khoản không đủ và cần nạp tiền; khi biết số dư, error.data.balance_units và error.data.balance_cu chứa số dư còn lại (có thể âm). Key mới tạo có thể trả về -32021 (503) trong vài giây; chờ theo Retry-After rồi thử lại.
• Lỗi upstream: Mã -32603 do nền tảng tạo ra vì lỗi giao tiếp upstream hoặc phản hồi sai định dạng (upstream unavailable, no response from upstream, malformed upstream response) có data.reason: upstream_unavailable.
• Tính phí thông báo: Thông báo (204) được tính phí theo trọng số phương thức.

Bảng mã lỗi JSON-RPC

Quy tắc tính phí Data API

Data API cung cấp dữ liệu chuỗi chỉ đọc qua các endpoint REST. Cách tính phí và xử lý lỗi tuân theo các quy tắc sau:

Chi tiết quy tắc

• Chỉ phản hồi thành công 2xx bị tính phí.
• Thao tác không khả dụng ngoài phạm vi bao phủ (chẳng hạn chuỗi không được hỗ trợ hoặc khối ngoài phạm vi bao phủ trace) trả về HTTP 422 no_coverage, không tính phí nhưng được tính vào giới hạn tốc độ.
• Phản hồi HTTP 401, 402, 404 và 429 không bị tính phí. Về header phản hồi (x-bv-meter: 1), xem Mã trạng thái HTTP và quy tắc tính phí.

Bảng mã trạng thái Data API

Truy vấn số dư (GET /v1/account)

Người có API key có thể kiểm tra trực tiếp số dư và chi tiết hạn mức của key mà không bị tính phí hay trừ Compute Units (CU):

curl -H "x-api-key: $BLOCKVECTRA_API_KEY" https://api.blockvectra.com/v1/account

• Miễn phí và không tính phí: GET /v1/account miễn phí. Endpoint này không bao giờ tính phí, không trừ CU và trả về HTTP 200 với số dư hiện tại ngay cả khi số dư bằng không hoặc âm (không bao giờ trả về 402).
• Xác thực: Xác thực key chỉ dùng header x-api-key (không chấp nhận key trong đường dẫn hoặc Bearer token). Thiếu header trả về 401 missing_api_key; key không hợp lệ hoặc đã bị thu hồi trả về 401 invalid_api_key. (Key hết hạn trả về 403 key_expired; dịch vụ tạm thời không khả dụng trả về 503 auth_unavailable hoặc billing_unavailable kèm Retry-After.)
• Giới hạn tốc độ: Có giới hạn riêng 5 yêu cầu mỗi giây cho mỗi ID key, độc lập với đo mức sử dụng CU và tính phí. Vượt giới hạn trả về HTTP 429 rate_limited kèm header Retry-After.

Các trường phản hồi:

• key_id: Chuỗi định danh của API key.
• plan: Loại gói tài khoản (free khi tài khoản có hạn mức tốc độ gọi của gói miễn phí; paid trong trường hợp còn lại).
• balance_units: Số dư tài khoản còn lại theo đơn vị (có thể bằng không hoặc âm).
• balance_cu: Số dư còn lại được quy đổi sang Compute Units (CU).
• balance_as_of_age_ms: Số mili giây đã trôi qua kể từ khi số dư được đọc từ nguồn dữ liệu.
• key: Các giới hạn và chi tiết hạn mức riêng của key:
  • cu_per_sec: Tốc độ nạp lại token bucket theo CU mỗi giây.
  • burst_cu: Dung lượng burst của token bucket theo CU.
  • cu_cap: Giới hạn CU suốt vòng đời của key này, hoặc null nếu không có giới hạn.
  • cu_cap_remaining: CU còn lại trong giới hạn cu_cap, hoặc null nếu không có giới hạn (có thể bằng không hoặc âm).
  • expires_at: Dấu thời gian hết hạn RFC 3339, hoặc null nếu key không bao giờ hết hạn.

Ví dụ phản hồi:

{
  "key_id": "<key_id>",
  "plan": "<plan>",
  "balance_units": <integer>,
  "balance_cu": <integer>,
  "balance_as_of_age_ms": <integer>,
  "key": {
    "cu_per_sec": <integer>,
    "burst_cu": <integer>,
    "cu_cap": <integer_or_null>,
    "cu_cap_remaining": <integer_or_null>,
    "expires_at": "<expires_at_or_null>"
  }
}

Bảng giá và nâng cấp

Chi phí cụ thể của mọi lệnh gọi bị tính phí được xác định bởi trọng số CU đã công bố:

• Để xem trọng số của tất cả phương thức và thao tác, xem bảng trọng số phương thức và Quy tắc đo mức sử dụng CU JSON-RPC.
• Để biết giá gói và chi tiết quyết toán, xem Trang bảng giá.
• Nâng cấp lên gói trả phí: nạp tiền trả phí gỡ bỏ giới hạn lệnh gọi mỗi giây của gói miễn phí; mỗi key vẫn chịu giới hạn tốc độ CU và burst.

Quy trình nạp tiền on-chain

Khi số dư tài khoản không đủ hoặc bạn cần thông lượng cao hơn, nạp tiền on-chain trong console theo các bước sau:

1. Đăng nhập vào Console: Đăng nhập vào BlockVectra Console.
2. Mở trang Thanh toán: Đi tới trang Thanh toán.
3. Lấy địa chỉ riêng của bạn: Trong thẻ nạp tiền on-chain, sao chép địa chỉ nạp tiền riêng của tài khoản hoặc quét mã QR.
4. Chuyển tiền: Chỉ chuyển bằng các mạng được hỗ trợ và USDC / USDT / USDG được liệt kê trên trang. Các mạng được hỗ trợ và số tiền nạp tối thiểu được hiển thị trong console.
5. Tự động ghi có: Khi được phát hiện on-chain, giao dịch hiển thị là "Đang xử lý"; khi được ghi có, tín dụng tự động được cộng vào số dư của bạn.

Lưu ý quan trọng:

• Chỉ dùng mạng và token được liệt kê rõ trong console. Khoản chuyển trên chuỗi không được hỗ trợ hoặc bằng token sai không thể được ghi có tự động.
• Đảm bảo mỗi khoản chuyển đáp ứng số tiền nạp tối thiểu được chỉ định trong console.
• Sau khi khoản nạp trả phí đầu tiên được ghi có, tài khoản của bạn được nâng cấp lên tài khoản trả phí, gỡ bỏ giới hạn lệnh gọi mỗi giây của gói miễn phí.

Agent hoặc chương trình server có thể gọi trực tiếp các endpoint nạp tiền bằng API key; xem hướng dẫn nạp tiền bằng chương trình cho Agent.

Tính phí Webhook push

Push có trọng số riêng cho sự kiện dữ liệu đã giao, truy vấn lịch sử thành công và địa chỉ-ngày tính phí. Các lệnh gọi quản lý ngoài lịch sử sự kiện, lần giao thất bại, thử lại tự động và sự kiện điều khiển đều miễn phí. Mỗi sự kiện đã giao được tính phí một lần; replay do khách hàng yêu cầu và sự kiện canonical được giao lại sau reorg là lần giao mới bị tính phí. Phí địa chỉ dùng số địa chỉ tối đa của mỗi đăng ký trong thời gian trực tuyến của ngày UTC; hạn mức địa chỉ miễn phí của tài khoản được chia sẻ giữa các đăng ký, với đăng ký cũ hơn dùng trước. Một địa chỉ trong hai đăng ký được tính hai lần; thêm chuỗi thay đổi phí sự kiện, không thay đổi phí địa chỉ.

Xem hướng dẫn Blockchain Webhook API để thiết lập, xác minh chữ ký và khôi phục giao dữ liệu. Hướng dẫn thanh toán stablecoin trình bày xác thực biên nhận và tải bù bằng polling; đăng ký WebSocket dùng cách đo mức sử dụng riêng cho kết nối và thông báo. Các lỗi yêu cầu được liệt kê trong tài liệu tham khảo lỗi. Các trọng số bên dưới lấy từ GET /v1/plans.

Các bước tiếp theo

• Khám phá danh mục bộ dữ liệu để xem mọi bộ dữ liệu mà BlockVectra lập chỉ mục.
• Xem gói miễn phí và bảng giá để kiểm tra những gì tài khoản của bạn bao gồm.
• Đăng nhập vào console để tạo API key.