# Referensi Error

> Source: https://docs.blockvectra.com/id/errors/

Referensi ini mendokumentasikan semua kode error dan nilai `reason` yang dapat dibaca mesin di seluruh layanan BlockVectra, termasuk apakah panggilan yang ditolak ditagih, kebijakan percobaan ulang, durasi backoff, dan tindakan yang disarankan untuk agen AI dan klien otomatis.

Untuk konsumsi yang dapat dibaca mesin, ambil katalog lengkap dalam format JSON di [/errors.json](https://docs.blockvectra.com/errors.json). Setiap respons error yang menyertakan `docs_url` menautkan langsung ke jangkar stabil di halaman ini: `https://docs.blockvectra.com/en/errors/#<reason>` (atau `#-<code-number>` untuk error tanpa kode alasan).

### Error JSON-RPC



| HTTP | Kode | Alasan | Arti | Ditagih | Dapat diulang | Waktu Tunggu (Retry-After) | Tindakan Agen |
| --- | --- | --- | --- | --- | --- | --- | --- |
| 401 | -32024 | `missing_api_key` | `API key tidak ada: kirimkan di jalur permintaan (/v1/{chain}/<api_key>) atau di header x-api-key` | Tidak | Tidak | — | Untuk endpoint JSON-RPC (/v1/{chain}), berikan API key di jalur permintaan (/v1/{chain}/<api_key>) atau di header x-api-key. Untuk Top-up API (/v1/topup/*), berikan API key hanya di header x-api-key. |
| 401 | -32024 | `invalid_api_key` | `API key tidak dikenal, dinonaktifkan, atau dicabut: JSON-RPC dan Data API mengembalikan HTTP 401 dengan struktur respons error invalid_api_key (JSON-RPC: error.code -32024 dan error.data.reason invalid_api_key; Data API: error.code dan error.data.reason invalid_api_key).` | Tidak | Tidak | — | Periksa API key; jika perlu, masuk kembali di konsol atau melalui pendaftaran terprogram untuk membuat API key baru (lihat [Kehilangan sesi atau API key Anda?](https://docs.blockvectra.com/en/guides/programmatic-signup/#lost-your-session-or-api-key)). |
| 403 | -32025 | `key_expired` | `API key telah kedaluwarsa; buat API key baru di konsol` | Tidak | Tidak | — | API key telah kedaluwarsa; buat API key baru di konsol atau melalui pendaftaran terprogram. |
| 403 | -32025 | `key_cap_exhausted` | `Batas CU API key habis; buat API key baru di konsol` | Tidak | Tidak | — | Batas seumur hidup CU API key habis; buat API key baru di konsol atau melalui pendaftaran terprogram. |
| 503 | -32021 | `auth_unavailable` | `Data autentikasi untuk sementara tidak tersedia` | Tidak | Ya | Patuhi header Retry-After (detik) | Server untuk sementara tidak dapat memverifikasi API key; ini bukan masalah dengan API key Anda. Tunggu sesuai Retry-After dan coba lagi; **jangan membuat ulang API key**. |
| 404 | -32600 | `unknown_chain` | `Rantai tidak dikenal` | Tidak | Tidak | — | Kueri rantai yang tersedia dengan GET /v1/chains atau alat list_chains; verifikasi jalur URL. |
| 404 | 404 | `unknown_endpoint` | `Metode dan jalur Data API tidak cocok dengan operasi yang dikenal` | Tidak | Tidak | — | Verifikasi metode dan jalur URL terhadap dokumentasi Data API. |
| 200 | -32700 | `parse_error` | `Error penguraian JSON` | Tidak | Tidak | — | Verifikasi sintaksis JSON yang valid di badan permintaan sebelum mengirim. |
| 200 | -32600 | `invalid_request` | `Permintaan tidak valid` | Tidak | Tidak | — | Periksa struktur permintaan; verifikasi kolom jsonrpc: '2.0', id, dan method sebelum mengirim ulang. |
| 200 | -32602 | `invalid_params` | `Tracer tidak diizinkan` | Tidak | Tidak | — | Sesuaikan parameter metode; verifikasi tracer yang didukung dan batas waktu tunggu rantai. |
| 200 | -32602 | `logs_range_too_large` | `Rentang blok eth_getLogs terlalu besar: maksimum <N> blok` | Tidak | Tidak | — | Persempit rentang blok kueri agar berada dalam max_logs_block_range yang ditunjukkan di GET /v1/chains. |
| 429 | -32005 | `public_rate_limit` | `Batas laju IP publik terlampaui` | Tidak | Ya | Patuhi header Retry-After (detik) | Tunggu sesuai header Retry-After lalu coba lagi, atau kirim permintaan dengan API key. [Dapatkan API key](https://blockvectra.com/en/get-api-key/?ref=err-public). |
| 429 | -32005 | `public_pool_busy` | `Kapasitas kumpulan bersama publik saat ini penuh` | Tidak | Ya | Patuhi header Retry-After atau tunggu beberapa detik lalu coba lagi dengan backoff | Coba lagi dengan backoff, atau kirim permintaan dengan API key. [Dapatkan API key](https://blockvectra.com/en/get-api-key/?ref=err-public). |
| 200 | -32601 | `method_not_public` | `Metode ini tidak terbuka untuk akses publik tanpa key` | Tidak | Tidak | — | Gunakan metode yang didukung endpoint publik, atau kirim permintaan dengan API key. [Dapatkan API key](https://blockvectra.com/en/get-api-key/?ref=err-public). |
| 200 | -32601 | `method_not_allowed` | `Metode tidak tersedia pada rantai ini atau dinonaktifkan oleh kebijakan` | Tidak | Tidak | — | Periksa methods.allow dan methods.deny di GET /v1/chains untuk metode yang didukung. Dukungan pengiriman transaksi ditentukan oleh methods.allow di GET /v1/chains. Pengiriman transaksi saat ini tidak tersedia di: HyperEVM. |
| 200 | -32601 | `subscription_not_available` | `Jenis langganan WebSocket tidak tersedia` | Tidak | Tidak | — | Periksa jenis langganan yang didukung di GET /v1/chains (kolom ws dan subscriptions). |
| 200 | -32602 | `logs_filter_required` | `Langganan logs WebSocket memerlukan address atau topic0 (nilai non-null pada posisi pertama topics)` | Tidak | Tidak | — | Tentukan address atau topic0 non-null pada posisi pertama topics dalam filter langganan logs. |
| 200 | -32600 | `batch_too_large` | `Batch terlalu besar: maksimum <N> panggilan` | Tidak | Tidak | — | Bagi batch menjadi batch yang lebih kecil sesuai batas jumlah panggilan yang ditunjukkan dalam data error. |
| 413 | 413 | `request_too_large` | `Badan permintaan Data API melebihi batas ukuran` | Tidak | Tidak | — | Kurangi ukuran badan permintaan. |
| 200 | -32000 | `not_found` | `Transaksi tidak ditemukan` | Tidak | Tidak | — | Jika baru dikirim atau ditambang, tunggu propagasi lalu coba lagi; jika tidak, periksa nomor blok atau hash. |
| 200 | -32011 | `state_window` | `Status historis tidak tersedia di luar <N> blok terbaru` | Tidak | Tidak | — | Kueri blok dalam state_window_blocks yang dilaporkan GET /v1/chains, atau gunakan Data API untuk data historis. |
| 200 | -32011 | `range_not_indexed` | `Rentang blok yang diminta belum sepenuhnya diindeks` | Tidak | Tidak | — | Persempit riwayat yang diminta ke rentang yang telah diindeks; jangan mengulang rentang yang sama tanpa perubahan jika belum tercakup. |
| 200 | -32011 | `history_not_ready` | `Data riwayat yang diminta belum siap` | Tidak | Ya | Tunggu pengindeksan menyusul data; patuhi error.data.retry_after_seconds jika tersedia | Coba lagi setelah pengindeksan menyusul data, dengan menunggu error.data.retry_after_seconds jika diberikan. |
| 429 | -32005 | `key_rate_limit` | `Batas laju CU API key terlampaui` | Tidak | Ya | Patuhi header Retry-After (detik) | Tunggu durasi yang ditentukan dalam header Retry-After sebelum mencoba lagi, atau distribusikan beban. |
| 429 | rate_limited | `rate_limited` | `Batas laju permintaan terlampaui pada API atau GET /v1/account (lebih dari 5 permintaan per detik untuk API key ini)` | Tidak | Ya | Patuhi header Retry-After | Tunggu durasi Retry-After sebelum mencoba lagi. |
| 429 | -32005 | `concurrency_limit` | `Batas konkurensi permintaan simultan terlampaui` | Tidak | Ya | Patuhi header Retry-After atau tunggu panggilan aktif selesai | Batasi ukuran kumpulan permintaan bersamaan klien dan coba lagi saat slot tersedia. |
| 429 | -32005 | `free_plan_call_limit` | `Batas laju panggilan paket gratis terlampaui` | Tidak | Ya | Tunggu 1 detik dan coba lagi | Kurangi laju permintaan atau lakukan top-up untuk membuka throughput tingkat berbayar. |
| 429 | -32022 | `request_exceeds_burst` | `Biaya CU permintaan atau batch melebihi kapasitas burst API key` | Tidak | Tidak | — | Menunggu tidak akan berhasil; bagi batch atau kurangi parameter metode agar sesuai kapasitas burst. |
| 429 | -32022 | `free_plan_batch_too_large` | `Permintaan berisi <N> panggilan, melebihi batas paket gratis <M> panggilan per detik` | Tidak | Tidak | — | Menunggu tidak akan berhasil; bagi batch agar jumlah panggilan berada dalam batas paket gratis, atau lakukan top-up. |
| 429 | -32005 | `ws_connection_limit` | `Batas koneksi WebSocket untuk API key atau akun ini tercapai` | Tidak | Tidak | — | Tutup koneksi WebSocket yang tidak terpakai atau gunakan kembali koneksi yang ada. |
| 200 | -32022 | `subscription_limit` | `Batas jumlah langganan per koneksi WebSocket tercapai` | Tidak | Tidak | — | Batalkan langganan yang ada atau buka koneksi lain. |
| 200 | -32005 | `ws_filter_capacity` | `Filter logs WebSocket mencapai kapasitas maksimum` | Tidak | Tidak | — | Batalkan langganan logs yang ada atau gunakan filter yang lebih sempit. |
| 200 | -32026 | `ws_push_overloaded` | `Antrean push WebSocket kelebihan beban` | Tidak | Ya | Coba lagi nanti dengan backoff, atau hubungkan kembali | Coba lagi eth_subscribe dengan backoff eksponensial, atau hubungkan kembali. Langganan yang ada tetap menerima notifikasi. |
| 200 | -32005 | `overloaded` | `Layanan untuk sementara kelebihan beban` | Tidak | Ya | Tunggu beberapa detik lalu coba lagi dengan backoff eksponensial | Gunakan backoff dengan jitter lalu coba lagi permintaan. |
| 402 | -32020 | `balance_exhausted` | `Saldo tidak mencukupi (jika saldo diketahui, error.data menyertakan balance_units dan balance_cu)` | Tidak | Tidak | — | Isi ulang on-chain: dapatkan alamat deposit dari konsol atau `GET /v1/topup/deposit-address` (MCP `get_deposit_address`); lihat [panduan top-up untuk agent](https://docs.blockvectra.com/en/guides/agent-topup/), atau gunakan reset kuota di konsol jika memenuhi syarat. Jika saldo diketahui, error.data berisi balance_units (negatif jika saldo terlampaui) dan balance_cu. |
| 402 | -32020 | `free_grant_exhausted` | `Kuota gratis habis (jika saldo diketahui, error.data menyertakan balance_units dan balance_cu)` | Tidak | Tidak | — | Isi ulang on-chain: dapatkan alamat deposit dari konsol atau `GET /v1/topup/deposit-address` (MCP `get_deposit_address`); lihat [panduan top-up untuk agent](https://docs.blockvectra.com/en/guides/agent-topup/), gunakan reset kuota jika tersedia, atau tunggu kuota siklus berikutnya. Jika saldo diketahui, error.data berisi balance_units (negatif jika saldo terlampaui) dan balance_cu. |
| 503 | -32021 | `billing_unavailable` | `Layanan penagihan untuk sementara tidak dapat dihubungi` | Tidak | Ya | Patuhi header Retry-After (detik) | Ini bukan masalah saldo; API key yang baru dibuat tersinkron dalam beberapa detik. Tunggu sesuai Retry-After lalu coba lagi. |
| 200 | -32010 | `node_syncing` | `Node backend sedang dalam proses sinkronisasi` | Tidak | Ya | Tunggu beberapa detik lalu coba lagi | Tunggu sinkronisasi node selesai, atau periksa GET /v1/status. |
| 200 | -32603 | `upstream_unavailable` | `Node atau layanan hulu tidak tersedia` | Tidak | Ya | Tunggu beberapa detik lalu coba lagi | Coba lagi dengan backoff eksponensial; periksa GET /v1/status untuk kondisi node. |
| 504 | 504 | `upstream_timeout` | `Waktu tunggu permintaan ke node hulu habis` | Tidak | Ya | Coba lagi setelah jeda singkat | Coba lagi permintaan dengan backoff eksponensial. |
| 200 | -32000 | `response_too_large` | `Respons dari node hulu melebihi batas ukuran server` | Tidak | Tidak | — | Persempit parameter kueri (misalnya kurangi rentang blok eth_getLogs atau minta trace yang lebih kecil). |
| 200 | -32603 | `internal_error` | `Kesalahan internal layanan` | Tidak | Tidak | — | Coba lagi permintaan; laporkan kegagalan berulang beserta waktu kejadian ke dukungan. |
| 200 | 4444 | — | `Riwayat yang telah dipangkas (pruned) tidak tersedia` | Tidak | Tidak | — | Blok berada di luar jendela riwayat yang disimpan node yang dipangkas; kueri blok historis melalui Data API. |
| 200 | -32000 | — | `Status riwayat tidak tersedia; data lama tidak tersedia karena pemangkasan` | Tidak | Tidak | — | Kueri blok dalam jendela status, atau gunakan Data API untuk kueri historis. |
| 200 | -32002 | — | `<node message>` | Tidak | Ya | Tunggu beberapa detik lalu coba lagi dengan batch yang lebih kecil | Kurangi jumlah panggilan per batch dan coba lagi. |
| 200 | -32003 | — | `<node message>` | Tidak | Tidak | — | Bagi batch menjadi beberapa batch yang lebih kecil. |
| 200 | -32601 | — | `<node message>` | Tidak | Tidak | — | Periksa methods.allow dan methods.deny di GET /v1/chains untuk metode yang didukung. Dukungan pengiriman transaksi ditentukan oleh methods.allow di GET /v1/chains. Pengiriman transaksi saat ini tidak tersedia di: HyperEVM. |
| 200 | -32603 | — | `<node message>` | Tidak | Ya | Coba lagi setelah jeda singkat | Coba lagi permintaan; laporkan kegagalan berulang beserta waktu kejadian ke dukungan. |
| 200 | -32600 | — | `<node message>` | Tidak | Tidak | — | Periksa setiap permintaan dalam batch untuk parameter yang tidak sesuai; bagi batch lalu coba lagi. |
| 200 | * | — | `<node message>` | Ya | Tidak | — | Node telah melakukan komputasi dan panggilan ditagih. Periksa alasan/data revert atau parameter panggilan; jangan mencoba lagi tanpa pemeriksaan. |
| 408 | 408 | — | `Permintaan mengalami waktu habis setelah 35 detik antara penerimaan header dan respons` | Mungkin | Ya | Tunggu beberapa detik sebelum mengulang panggilan baca | Panggilan mungkin telah mencapai node dan ditagih. Untuk operasi baca, coba lagi dengan backoff. Untuk operasi tulis (misalnya, eth_sendRawTransaction), periksa status transaksi terlebih dahulu melalui hash. |

### Kode Penutupan WebSocket

Kode penutupan koneksi WebSocket dan tindakan klien yang disarankan.

| Kode | Alasan | Arti | Dapat diulang | Waktu Tunggu (Retry-After) | Tindakan Agen |
| --- | --- | --- | --- | --- | --- |
| 1001 | — | `Koneksi menganggur (idle timeout)` | Ya | Hubungkan kembali sesuai kebutuhan | Hubungkan kembali koneksi WebSocket saat diperlukan. |
| 1003 | — | `Frame biner tidak diterima` | Tidak | — | Jangan menghubungkan ulang secara otomatis; kirim hanya frame teks UTF-8. |
| 1009 | — | `Pesan terlalu besar (melebihi batas 1 MiB)` | Tidak | — | Jangan menghubungkan ulang secara otomatis; bagi permintaan besar agar tidak melebihi 1 MiB. |
| 1012 | — | `Restart layanan untuk pemeliharaan` | Ya | Hubungkan kembali dengan backoff dan jitter | Hubungkan kembali dengan backoff dan jitter, berlangganan kembali, dan isi kembali data yang terlewat. |
| 1013 | — | `Rantai tidak tersedia; layanan kelebihan beban` | Ya | Hubungkan kembali dengan backoff eksponensial dan full jitter | Hubungkan kembali dengan backoff eksponensial dan full jitter, berlangganan kembali, dan isi kembali data yang terlewat. |
| 4402 | — | `Saldo akun tidak mencukupi` | Tidak | — | Jangan menghubungkan ulang secara otomatis; isi ulang on-chain: dapatkan alamat deposit dari konsol atau `GET /v1/topup/deposit-address` (MCP `get_deposit_address`); lihat [panduan top-up untuk agent](https://docs.blockvectra.com/en/guides/agent-topup/), atau gunakan reset kuota di konsol jika memenuhi syarat. |
| 4404 | — | `API key tidak valid, dinonaktifkan, atau dicabut` | Tidak | — | Jangan menghubungkan ulang secara otomatis; verifikasi atau rotasi API key di konsol. |
| 4408 | — | `Layanan menutup sesi yang antrean push-nya melebihi 512 KiB (524.288 byte) dan membuang notifikasi yang tertunda; klien mungkin tidak menerima frame penutupan (browser melaporkan 1006); perlakukan pemutusan tak terduga seperti 4408.` | Ya | Hubungkan kembali dengan backoff; kurangi langganan atau baca lebih cepat | Perlakukan pemutusan tak terduga tanpa frame penutupan (browser melaporkan 1006) seperti 4408: hubungkan kembali dengan backoff, pulihkan langganan, dan isi kembali data yang hilang dengan eth_getLogs; kurangi langganan atau baca lebih cepat. |
| 4429 | — | `Laju pesan push melebihi batas` | Ya | Hubungkan kembali dengan backoff atau kurangi langganan | Kurangi langganan atau hubungkan kembali dengan backoff. |
| 4503 | — | `Layanan penagihan untuk sementara tidak tersedia` | Ya | Hubungkan kembali dengan backoff eksponensial dan full jitter | Hubungkan kembali dengan backoff eksponensial dan full jitter, lalu berlangganan kembali. |

### Error Data API

Error yang dikembalikan oleh endpoint Data API blockchain di bawah /v1/data/{chain}/.

| HTTP | Kode | Alasan | Arti | Ditagih | Dapat diulang | Waktu Tunggu (Retry-After) | Tindakan Agen |
| --- | --- | --- | --- | --- | --- | --- | --- |
| 400 | bad_request | — | `Parameter kueri duplikat, string kueri tidak valid, atau permintaan salah bentuk` | Tidak | Tidak | — | Periksa parameter kueri; pastikan parameter seperti limit muncul paling banyak sekali dan semua parameter kueri valid. |
| 409 | not_indexed_yet | — | `Nomor blok atau jendela yang diminta berada di atas as_of_block, atau hash merujuk ke blok di atas as_of_block (menyertakan indexed_through kecuali rantai belum memiliki blok yang diindeks)` | Tidak | Ya | Tunggu beberapa detik hingga indexed_through mencapai blok | Lakukan polling hingga blok yang diminta atau to_block tidak melebihi indexed_through, atau tunggu rantai mulai menulis blok. |
| 409 | window_too_large | — | `Jendela blok mencakup lebih dari 100.000 blok dan parameter clamp tidak disetel ke true` | Tidak | Tidak | — | Persempit rentang blok (from_block hingga to_block) menjadi <= 100.000 blok, atau kirim clamp=true. |
| 409 | too_many_pools | — | `Token cocok dengan lebih dari 200 kumpulan likuiditas; lakukan kueri berdasarkan dimensi pool` | Tidak | Tidak | — | Gunakan kueri berdasarkan dimensi pool secara langsung alih-alih seluruh token. |
| 409 | span_exceeded | — | `Rentang tanggal yang diminta melebihi batas maksimum 90 hari` | Tidak | Tidak | — | Persempit rentang tanggal antara from_time dan to_time menjadi maksimum 90 hari. |
| 422 | no_coverage | — | `Fitur tidak didukung pada rantai ini, atau blok yang diminta berada sebelum jendela cakupan` | Tidak | Tidak | — | Periksa `features` dan `coverage.from_block` di GET /v1/data/chains (atau `data_features` di GET /v1/status gratis) sebelum melakukan kueri. |
| 503 | unavailable | — | `Layanan data untuk sementara tidak tersedia` | Tidak | Ya | Tunggu beberapa detik lalu coba lagi dengan backoff eksponensial | Coba lagi setelah jeda singkat dengan backoff eksponensial. |
| 402 | insufficient_balance | — | `Saldo berbayar atau kuota gratis habis (jika saldo diketahui, error.data menyertakan balance_units dan balance_cu)` | Tidak | Tidak | — | Isi ulang on-chain: dapatkan alamat deposit dari konsol atau `GET /v1/topup/deposit-address` (MCP `get_deposit_address`); lihat [panduan top-up untuk agent](https://docs.blockvectra.com/en/guides/agent-topup/), atau tunggu kuota gratis terisi kembali. |
| 429 | cost_exceeds_burst | — | `Biaya satu permintaan melebihi kapasitas burst API key` | Tidak | Tidak | — | Bagi permintaan menjadi permintaan yang lebih kecil; mengulang permintaan tanpa perubahan tidak akan pernah berhasil. |
| 503 | gateway_overloaded | — | `Kapasitas Data API untuk sementara tidak tersedia` | Tidak | Ya | Retry-After: 1 detik | Kurangi permintaan bersamaan di seluruh API key dan rantai akun ini; tunggu Retry-After sebelum mencoba lagi. error.data.reason adalah null. |

### Error API Konsol, Akun & Faucet

Error yang dikembalikan oleh endpoint pengelolaan, pembuatan kunci, autentikasi, dan faucet di bawah /v1/.

| HTTP | Kode | Alasan | Arti | Ditagih | Dapat diulang | Waktu Tunggu (Retry-After) | Tindakan Agen |
| --- | --- | --- | --- | --- | --- | --- | --- |
| 409 | topup_disabled | — | `Pengisian ulang dihentikan sementara atau tidak ada jaringan isi ulang yang tersedia saat ini; alamat baru tidak dapat dialokasikan, tetapi alamat yang sudah dialokasikan tetap menjadi milik akun` | Tidak | Tidak | — | Periksa ketersediaan pengisian ulang di GET /v1/topup/status; coba lagi setelah pengisian ulang diaktifkan kembali. |
| 503 | deposit_unavailable | — | `Tidak dapat mengalokasikan alamat deposit untuk sementara waktu; coba lagi sesuai header Retry-After` | Tidak | Ya | Patuhi header Retry-After (detik) dan gunakan backoff eksponensial | Coba lagi sesuai header Retry-After dengan backoff eksponensial. |
| 400 | invalid_request | `invalid_username` | `Format nama pengguna tidak valid (harus alfanumerik atau garis bawah)` | Tidak | Tidak | — | Berikan nama pengguna yang valid sesuai persyaratan karakter dan panjang. |
| 400 | invalid_request | `expires_at` | `Waktu kedaluwarsa kunci tidak berada di masa depan atau melebihi masa berlaku maksimum kunci yang diizinkan` | Tidak | Tidak | — | Tetapkan expires_at ke waktu RFC 3339 di masa depan dalam masa berlaku yang diizinkan (default 365 hari), atau gunakan expires_in_secs. |
| 400 | invalid_request | `cu_cap` | `Parameter cu_cap berada di luar batas (harus berupa bilangan bulat antara 1 dan 9007199254740991)` | Tidak | Tidak | — | Tetapkan cu_cap ke bilangan bulat antara 1 dan 9007199254740991 atau hilangkan untuk CU tanpa batas. |
| 400 | siwe_invalid | `expired` | `Pesan Sign-In with Ethereum (SIWE) telah kedaluwarsa atau nonce sudah digunakan` | Tidak | Ya | Segera ambil challenge baru dan tandatangani | Minta challenge baru dari /v1/auth/siwe/challenge dan tandatangani pernyataan yang baru diterbitkan. |
| 400 | siwe_invalid | `chain_mismatch` | `chainId pesan SIWE tidak cocok dengan pengaturan server` | Tidak | Tidak | — | Gunakan chainId yang dikembalikan /v1/auth/siwe/challenge saat menyusun pesan SIWE. |
| 400 | siwe_invalid | `domain_mismatch` | `domain pesan SIWE tidak cocok dengan host server` | Tidak | Tidak | — | Pastikan domain dan uri cocok dengan host server yang dikembalikan dalam challenge. |
| 400 | siwe_invalid | `signature` | `Verifikasi tanda tangan kriptografi SIWE gagal` | Tidak | Tidak | — | Pastikan pesan ditandatangani dengan benar oleh kunci privat dompet yang bersangkutan. |
| 409 | key_limit_reached | `active_keys` | `Jumlah API key aktif (tidak dicabut) telah mencapai batas akun maksimum` | Tidak | Tidak | — | Cabut API key yang tidak lagi digunakan sebelum membuat yang baru. |
| 409 | no_reset_available | `nothing_to_reset` | `Saldo sudah berada pada atau di atas target reset; kesempatan reset dipertahankan` | Tidak | Tidak | — | Reset kuota tidak diperlukan saat ini karena saldo akun masih mencukupi. |
| 429 | rate_limited | `daily_creations` | `Batas pembuatan API key 24 jam akun telah tercapai` | Tidak | Ya | Patuhi header Retry-After (detik) | Rotasi API key yang ada alih-alih membuat yang baru, atau tunggu jendela 24 jam direset. |
| 429 | signup_rate_limited | `per_ip` | `Batas laju pendaftaran tercapai untuk subnet IP klien` | Tidak | Ya | Patuhi header Retry-After (detik) | Tunggu interval Retry-After sebelum membuat akun baru dari jaringan ini. |
| 429 | signup_rate_limited | `global` | `Batas laju pendaftaran pengguna baru global tercapai di semua sumber` | Tidak | Ya | Patuhi header Retry-After (detik) | Tunggu interval Retry-After sebelum mencoba lagi pembuatan akun. |
| 400 | oauth_invalid | — | `Parameter OAuth tidak valid atau state callback tidak dikenal, kedaluwarsa, atau sudah digunakan` | Tidak | Ya | — | Mulai alur login OAuth baru dari /v1/auth/{provider}/start. |
| 400 | login_code_invalid | — | `Login code tidak dikenal, kedaluwarsa, sudah digunakan, atau pemverifikasi PKCE tidak cocok` | Tidak | Tidak | — | Mulai ulang login untuk mendapatkan kode login baru. |
| 401 | unauthenticated | — | `Sesi tidak ada, atau token sesi tidak valid, kedaluwarsa, atau dicabut; pada Top-up API (/v1/topup/*), ini juga terjadi ketika header Authorization berisi token non-Bearer atau tidak valid alih-alih x-api-key` | Tidak | Tidak | — | Masuk kembali untuk mendapatkan token sesi Bearer baru; pada Top-up API, gunakan header x-api-key alih-alih Authorization untuk mengirim API key. |
| 403 | user_disabled | — | `Akun telah dinonaktifkan oleh administrasi` | Tidak | Tidak | — | Hubungi contact@blockvectra.com untuk dukungan akun. |
| 404 | provider_disabled | — | `Penyedia OAuth dikenali tetapi saat ini dinonaktifkan` | Tidak | Tidak | — | Gunakan SIWE atau penyedia autentikasi lain yang didukung. |
| 409 | identity_in_use | — | `Identitas (dompet atau akun OAuth) sudah ditautkan ke akun lain` | Tidak | Tidak | — | Lepaskan tautan identitas dari akun sebelumnya atau gunakan identitas lain. |
| 409 | identity_limit_reached | — | `Jumlah maksimum identitas tertaut (5) telah tercapai untuk akun ini` | Tidak | Tidak | — | Hapus salah satu identitas tertaut yang ada sebelum menambahkan identitas baru. |
| 409 | last_identity | — | `Tidak dapat membatalkan tautan identitas satu-satunya yang tersisa dari akun` | Tidak | Tidak | — | Tautkan identitas lain terlebih dahulu sebelum melepas identitas ini agar akun tidak kehilangan akses. |
| 409 | key_not_active | — | `Mencoba memutar API key yang dinonaktifkan, dicabut, atau kedaluwarsa` | Tidak | Tidak | — | Hanya API key aktif yang dapat diputar; buat API key baru sebagai gantinya. |
| 409 | no_reset_available | — | `Tidak ada kesempatan reset kuota yang tersisa pada akun ini` | Tidak | Tidak | — | Isi ulang on-chain: dapatkan alamat deposit dari konsol atau `GET /v1/topup/deposit-address` (MCP `get_deposit_address`); lihat [panduan top-up untuk agent](https://docs.blockvectra.com/en/guides/agent-topup/), atau tunggu siklus promosi berikutnya. |
| 413 | payload_too_large | — | `Badan permintaan melebihi batas ukuran 64 KiB` | Tidak | Tidak | — | Kurangi ukuran muatan permintaan di bawah 64 KiB. |
| 503 | signup_paused | — | `Pendaftaran pengguna baru global dihentikan sementara; login yang ada tidak terpengaruh` | Tidak | Ya | Coba lagi nanti | Pendaftaran pengguna baru dihentikan sementara; periksa status dan coba lagi nanti. |
| 503 | usage_unavailable | — | `Layanan pelaporan penggunaan untuk sementara tidak tersedia` | Tidak | Ya | Tunggu beberapa detik lalu coba lagi | Hanya memengaruhi endpoint /usage; endpoint lain berjalan normal. Coba lagi sebentar lagi. |
| 500 | internal | — | `Kesalahan server yang tidak terduga` | Tidak | Ya | Coba lagi setelah jeda singkat | Coba lagi permintaan dengan backoff eksponensial. |
| 400 | invalid_address | `invalid_address` | `Format alamat penerima atau checksum tidak valid` | Tidak | Tidak | — | Gunakan 0x diikuti 40 karakter heksadesimal, huruf kecil atau checksum EIP-55; periksa data.field (/address). |
| 503 | faucet_empty | `faucet_empty` | `Saldo faucet tidak mencukupi untuk klaim dan biaya transaksi` | Tidak | Ya | Patuhi header Retry-After (detik) | Tunggu Retry-After sebelum mencoba lagi; jangan menganggap ETH uji sudah dikirim tanpa respons penerimaan. |
| 503 | service_unavailable | `service_unavailable` | `Pemrosesan klaim faucet untuk sementara tidak tersedia, atau klaim sebelumnya belum memiliki tanda terima` | Tidak | Ya | Patuhi header Retry-After (detik) | Tunggu Retry-After sebelum mencoba lagi; jangan menganggap ETH uji sudah dikirim tanpa respons penerimaan. |

### Error Push API

Error dari pengelolaan langganan webhook dan riwayat peristiwa di bawah /v1/push/.

| HTTP | Kode | Alasan | Arti | Ditagih | Dapat diulang | Waktu Tunggu (Retry-After) | Tindakan Agen |
| --- | --- | --- | --- | --- | --- | --- | --- |
| 400 | invalid_request | — | `Kolom permintaan, alamat, paginasi, atau rentang blok tidak valid.` | Tidak | Tidak | — | Periksa data.field dan data.invalid; perbaiki permintaan. |
| 401 | missing_api_key | — | `Header x-api-key tidak ada.` | Tidak | Tidak | — | Sertakan API key yang valid di header x-api-key. |
| 401 | invalid_api_key | — | `API key tidak dikenal, dinonaktifkan, atau dicabut.` | Tidak | Tidak | — | Gunakan API key aktif dari akun Anda. |
| 402 | insufficient_balance | — | `Saldo atau tunjangan gratis habis untuk kueri riwayat peristiwa.` | Tidak | Tidak | — | Periksa data.reason (balance_exhausted atau free_grant_exhausted) dan data.balance_units / data.balance_cu jika tersedia; isi ulang melalui data.topup_url atau data.deposit_address_url. |
| 403 | key_cap_exhausted | — | `Batas CU API key habis untuk kueri riwayat peristiwa.` | Tidak | Tidak | — | Periksa data.cu_cap dan buat API key baru di konsol. |
| 403 | key_expired | — | `API key telah kedaluwarsa.` | Tidak | Tidak | — | Gunakan API key yang belum kedaluwarsa dari akun Anda. |
| 404 | not_found | — | `Rute, metode, atau langganan tidak ditemukan.` | Tidak | Tidak | — | Periksa jalur, metode, dan kepemilikan langganan. |
| 409 | limit_reached | — | `Batas langganan akun atau batas pasangan alamat tercapai.` | Tidak | Tidak | — | Periksa data.limit dan data.max; kurangi langganan atau alamat. |
| 413 | request_too_large | — | `Badan permintaan melebihi batas rute.` | Tidak | Tidak | — | Kurangi ukuran muatan permintaan. |
| 422 | chain_not_available | — | `Rantai tidak tersedia untuk push atau tidak ada dalam langganan.` | Tidak | Tidak | — | Periksa GET /v1/push/chains dan chains langganan. |
| 422 | chains_required | — | `Setidaknya satu rantai diperlukan.` | Tidak | Tidak | — | Berikan objek chains yang tidak kosong; gunakan status offline untuk berhenti mendengarkan. |
| 422 | confirmations_out_of_range | — | `Kedalaman konfirmasi berada di luar rentang rantai.` | Tidak | Tidak | — | Pilih confirmations dalam rentang data.min hingga data.max. |
| 422 | destination_not_allowed | — | `URL penerima tidak diizinkan.` | Tidak | Tidak | — | Periksa data.rule; gunakan nama host HTTPS pada port 443 tanpa informasi pengguna atau fragment. |
| 422 | block_out_of_range | — | `Rentang blok berada di luar cakupan pemutaran ulang atau riwayat yang tersedia.` | Tidak | Tidak | — | Gunakan data.min_block dan data.max_block untuk menyesuaikan rentang. |
| 429 | cost_exceeds_burst | — | `Biaya permintaan riwayat melebihi kapasitas burst API key.` | Tidak | Tidak | — | Periksa data.reason (request_exceeds_burst) dan data.max; tingkatkan kapasitas burst sebelum mencoba lagi. Mengulang tanpa perubahan tidak membantu. |
| 429 | rate_limited | — | `Batas laju antarmuka manajemen atau kueri riwayat tercapai.` | Tidak | Ya | Patuhi header Retry-After | Untuk riwayat, periksa data.reason (key_rate_limit atau free_plan_call_limit); tunggu detik dalam Retry-After dan kurangi frekuensi atau konkurensi permintaan. |
| 500 | internal_error | — | `Kesalahan layanan yang tidak terduga.` | Tidak | Tidak | — | Simpan x-request-id dan hubungi dukungan. |
| 503 | auth_unavailable | — | `Validasi API key untuk sementara tidak tersedia.` | Tidak | Ya | Tunggu detik dalam Retry-After. | Tunggu detik dalam Retry-After sebelum mencoba lagi. |
| 503 | billing_unavailable | — | `Status penagihan riwayat untuk sementara tidak tersedia.` | Tidak | Ya | Tunggu detik dalam Retry-After. | Tunggu detik dalam Retry-After sebelum mencoba lagi. |
| 503 | upstream_unavailable | — | `Layanan push untuk sementara tidak dapat dijangkau.` | Tidak | Ya | Tunggu detik dalam Retry-After. | Tunggu detik dalam Retry-After sebelum mencoba lagi. |
| 503 | service_unavailable | — | `Layanan push atau kapasitas alamat untuk sementara tidak tersedia.` | Tidak | Ya | Patuhi header Retry-After | Tunggu detik yang ditentukan dalam header Retry-After sebelum mencoba lagi. |

Untuk error langganan atau replay Webhook, ikuti [panduan pemulihan pengiriman Push](https://docs.blockvectra.com/en/guides/webhook-push/#delivery-retries-and-replay). Integrasi penerima dimulai dengan [verifikasi tanda tangan body mentah](https://docs.blockvectra.com/en/guides/webhook-push/#verify-signatures); [contoh pembayaran stablecoin](https://docs.blockvectra.com/en/guides/stablecoin-payments/#receive-payments-with-webhooks) menambahkan deduplikasi peristiwa, pemeriksaan tanda terima, pengambilan riwayat celah, dan rekonsiliasi reorg. Lihat [aturan penagihan](https://docs.blockvectra.com/en/guides/billing-rules/#webhook-push-billing) untuk pengukuran dan [koneksi ulang WebSocket](https://docs.blockvectra.com/en/guides/websocket-subscriptions/#reconnection-and-exponential-backoff) untuk langganan berbasis koneksi.

Untuk `logs_range_too_large`, periksa [parameter metode eth\_getLogs](https://docs.blockvectra.com/en/api/json-rpc/methods/eth_getLogs/) dan ikuti [panduan batas rentang blok dan kueri terbagi](https://docs.blockvectra.com/en/guides/getlogs-block-range/).

Untuk klaim faucet di Robinhood Chain, lihat [panduan faucet testnet](https://docs.blockvectra.com/en/guides/robinhood-testnet-faucet/) untuk kelayakan dan penanganan kode error bersama.