Apa yang tidak ditagih: kode error dan aturan penagihan

BlockVectra mengukur permintaan dalam Compute Units (CU). Panggilan JSON-RPC dan Data API ditagih hanya setelah respons diperoleh. Panduan ini merangkum aturan penentuan penagihan untuk kode status HTTP, panggilan JSON-RPC, dan Data API, beserta tindakan yang direkomendasikan bagi pengembang.

Kode status HTTP dan aturan penagihan

Aturan penentuan penagihan dan penanganan respons pada tingkat HTTP adalah sebagai berikut:

Catatan: Saat diakses melalui Cloudflare, Cloudflare dapat mengembalikan halaman error 52x atau 1015; halaman tersebut tidak dihasilkan oleh layanan ini.

Header respons biaya dan saldo: Saat mengirim x-bv-meter: 1 pada permintaan HTTP (berlaku untuk JSON-RPC dan Data API), respons yang menagih setidaknya satu panggilan mengembalikan x-bv-cu-charged (Compute Units yang ditagih untuk permintaan ini, atau total panggilan yang ditagih dalam batch) dan x-bv-balance-units (sisa unit saldo akun tepat setelah biaya ini dikenakan, negatif saat saldo terlampaui; tidak disertakan jika saldo tidak diketahui). Permintaan tanpa x-bv-meter: 1, respons tanpa panggilan yang ditagih, dan respons error 402, 403, 429, atau 503 tidak menyertakan kedua header tersebut. Header respons ini dapat diakses oleh skrip browser melalui CORS, sedangkan WebSocket tidak menggunakannya. Saldo dikurangi total penggunaan yang belum diselesaikan, yang dibulatkan ke atas satu kali ke unit utuh; penyelesaian per jam membulatkan ke bawah, sehingga saldo yang dilaporkan dapat naik hingga satu unit setelah penyelesaian.

Kode error JSON-RPC dan aturan penagihan

Kode error yang sama dapat berasal dari platform atau node, dan penagihannya berbeda:

• Error yang dihasilkan oleh platform sendiri: tidak pernah ditagih;
• Error yang dikembalikan oleh node: diteruskan apa adanya dan ditagih sesuai bobot metode, dengan pengecualian hanya untuk kode error node yang tercantum di bawah.

Rincian aturan

• Error node yang tidak ditagih: -32002 (timeout batch), -32003 (respons batch terlalu besar), dan -32600 (batch ditolak seluruhnya) dari node menunjukkan bahwa node menghentikan panggilan lebih awal; error tersebut dan semua notifikasi dalam batch yang sama tidak ditagih. -32601 (metode yang diekspos belum diimplementasikan) dan -32603 (kegagalan internal node) dari node tidak ditagih melalui HTTP atau WebSocket dan tidak memengaruhi panggilan atau notifikasi lain dalam batch. Selain itu, 4444 (blok yang telah dipangkas) dan -32000 (state historis di luar jendela riwayat state node, yang ditentukan oleh state_window_blocks dalam GET /v1/chains) tidak ditagih dan tidak memengaruhi panggilan lain dalam batch.
• Error node yang ditagih: Error lain yang dikembalikan oleh node ditagih sesuai bobot metode jika melaporkan hasil eksekusi rantai, seperti execution reverted (-32000 atau 3 dengan data), serta -32602 invalid argument dari node sendiri.
• Pemeriksaan saldo dan sinkronisasi: -32020 menunjukkan saldo akun tidak mencukupi dan memerlukan top up; jika saldo diketahui, error.data.balance_units dan error.data.balance_cu memuat sisa saldo (dapat negatif). API key yang baru dibuat dapat mengembalikan -32021 (503) selama beberapa detik; tunggu sesuai Retry-After dan coba lagi.
• Kegagalan upstream: -32603 yang dihasilkan platform akibat kegagalan komunikasi upstream atau respons salah format (upstream unavailable, no response from upstream, malformed upstream response) menyertakan data.reason: upstream_unavailable.
• Penagihan notifikasi: Notifikasi (204) ditagih sesuai bobot metodenya.

Tabel kode error JSON-RPC

Aturan penagihan Data API

Data API menyajikan data rantai hanya-baca melalui endpoint REST. Penagihan dan penanganan error-nya mengikuti aturan berikut:

Rincian aturan

• Hanya respons berhasil 2xx yang ditagih.
• Operasi yang tidak tersedia di luar cakupan (seperti rantai yang tidak didukung atau blok di luar cakupan trace) mengembalikan HTTP 422 no_coverage, yang tidak ditagih tetapi diperhitungkan terhadap batas laju.
• Respons HTTP 401, 402, 404, dan 429 tidak ditagih. Untuk header respons (x-bv-meter: 1), lihat Kode status HTTP dan aturan penagihan.

Tabel kode status Data API

Kueri saldo (GET /v1/account)

Pemegang API key dapat memeriksa saldo dan rincian kuota API key secara langsung tanpa dikenakan biaya atau mengurangi Compute Units (CU):

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

• Gratis dan tidak ditagih: GET /v1/account gratis. Endpoint ini tidak pernah ditagih, tidak mengurangi CU, dan mengembalikan HTTP 200 dengan saldo saat ini meskipun nol atau negatif (tidak pernah mengembalikan 402).
• Autentikasi: Autentikasi API key hanya menggunakan header x-api-key (API key pada path dan token Bearer tidak diterima). Header yang tidak disertakan mengembalikan 401 missing_api_key; API key tidak valid atau dicabut mengembalikan 401 invalid_api_key. (API key kedaluwarsa mengembalikan 403 key_expired; layanan yang sementara tidak tersedia mengembalikan 503 auth_unavailable atau billing_unavailable dengan Retry-After.)
• Pembatasan laju: Memiliki batas tersendiri sebesar 5 permintaan per detik per ID API key, terpisah dari pengukuran CU dan penagihan. Melampaui batas mengembalikan HTTP 429 rate_limited dengan header Retry-After.

Bidang respons:

• key_id: String identitas API key.
• plan: Jenis paket akun (free jika akun memiliki kuota laju panggilan paket gratis; paid jika tidak).
• balance_units: Sisa saldo akun dalam unit (dapat nol atau negatif).
• balance_cu: Sisa saldo yang dikonversi menjadi Compute Units (CU).
• balance_as_of_age_ms: Milidetik yang telah berlalu sejak saldo dibaca dari sumber datanya.
• key: Batas dan rincian kuota khusus API key:
  • cu_per_sec: Laju pengisian ulang token bucket dalam CU per detik.
  • burst_cu: Kapasitas burst token bucket dalam CU.
  • cu_cap: Batas CU sepanjang masa berlaku API key ini, atau null jika tanpa batas.
  • cu_cap_remaining: Sisa CU di bawah cu_cap, atau null jika tanpa batas (dapat nol atau negatif).
  • expires_at: Timestamp kedaluwarsa RFC 3339, atau null jika API key tidak pernah kedaluwarsa.

Contoh respons:

{
  "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>"
  }
}

Harga dan peningkatan paket

Biaya spesifik untuk semua panggilan yang ditagih ditentukan oleh bobot CU yang dipublikasikan:

• Untuk memeriksa bobot semua metode dan operasi, lihat tabel bobot metode dan Aturan Pengukuran CU JSON-RPC.
• Untuk harga paket dan rincian penyelesaian, lihat halaman Harga.
• Meningkatkan ke paket berbayar: top up berbayar menghapus batas panggilan per detik Paket Gratis; setiap API key tetap tunduk pada batas laju CU dan burst.

Proses top up on-chain

Jika saldo akun Anda tidak mencukupi atau Anda membutuhkan throughput yang lebih tinggi, lakukan top up on-chain di konsol dengan langkah berikut:

1. Masuk ke Konsol: Masuk ke Konsol BlockVectra.
2. Buka Halaman Penagihan: Buka halaman Penagihan.
3. Dapatkan Alamat Khusus Anda: Pada kartu top up on-chain, salin alamat top up khusus akun Anda atau pindai kode QR.
4. Transfer Dana: Transfer hanya menggunakan jaringan yang didukung dan USDC / USDT / USDG yang tercantum pada halaman. Jaringan yang didukung dan jumlah top up minimum ditampilkan di konsol.
5. Saldo Masuk Otomatis: Setelah terdeteksi on-chain, transaksi ditampilkan sebagai "Sedang diproses"; setelah dikreditkan, kredit otomatis ditambahkan ke saldo Anda.

Catatan Penting:

• Gunakan hanya jaringan dan token yang secara eksplisit tercantum di konsol. Transfer pada rantai yang tidak didukung atau dengan token yang salah tidak dapat dikreditkan secara otomatis.
• Pastikan setiap transfer memenuhi jumlah top up minimum yang ditampilkan di konsol.
• Setelah top up berbayar pertama Anda dikreditkan, akun Anda ditingkatkan ke akun berbayar, menghapus batas panggilan per detik Paket Gratis.

Agent atau program server dapat langsung memanggil endpoint top up menggunakan API key; lihat panduan top up terprogram untuk Agent.

Penagihan push Webhook

Push memiliki bobot terpisah untuk peristiwa data yang terkirim, kueri riwayat yang berhasil, dan alamat-hari yang ditagih. Panggilan pengelolaan selain riwayat peristiwa, percobaan pengiriman yang gagal, percobaan ulang otomatis, dan peristiwa kontrol gratis. Setiap peristiwa yang terkirim ditagih satu kali; replay oleh pelanggan dan peristiwa kanonis yang dikirim ulang setelah reorg merupakan pengiriman baru yang ditagih. Biaya alamat menggunakan jumlah alamat maksimum setiap langganan saat online selama hari UTC; kuota alamat gratis akun dibagi di seluruh langganan, dengan langganan yang lebih lama menggunakannya terlebih dahulu. Alamat dalam dua langganan dihitung dua kali; menambahkan rantai mengubah biaya peristiwa, bukan biaya alamat.

Lihat panduan Blockchain Webhook API untuk penyiapan, verifikasi tanda tangan, dan pemulihan pengiriman. Panduan pembayaran stablecoin mencakup validasi receipt dan backfill dengan polling; langganan WebSocket menggunakan pengukuran koneksi dan notifikasinya sendiri. Error permintaan tercantum dalam referensi error. Bobot di bawah berasal dari GET /v1/plans.

Langkah selanjutnya

• Telusuri direktori dataset untuk melihat setiap dataset yang diindeks oleh BlockVectra.
• Lihat paket gratis dan harga untuk memeriksa apa yang termasuk dalam akun Anda.
• Masuk ke konsol untuk membuat API key.