Batas laju, error, dan penagihan

Batas laju

Batas berlaku per key, menurut mode akses:

Mode akses	Batas
free (metadata: health, me, discover)	60 permintaan/jam, dengan batas burst 1/detik
basic (berbayar, saat aktif)	1,000 permintaan/jam
premium (berbayar, saat aktif)	5,000 permintaan/jam
pro (berbayar, saat aktif)	15,000 permintaan/jam
partner / enterprise	dikonfigurasi admin
key sandbox cogv_test_ mana pun	25 permintaan/jam dan 100/hari

Key baru mulai hanya dengan akses metadata free. Akses trial diberikan oleh admin, terbatas dan bisa kedaluwarsa; batas partner dan enterprise dikonfigurasi per perjanjian - ajukan akses dari dApp. Header RateLimit-* standar dikembalikan; saat habis Anda mendapat 429 rate_limited.

Kode error

HTTP	error	Arti
400	bad_request / invalid_chain / invalid_address / invalid_wallet / invalid_token	input cacat; chain harus eth, base, atau bsc; alamat harus 0x + 40 heksadesimal
401	missing_api_key	tidak ada X-API-Key (atau Bearer) yang disertakan
401	invalid_api_key	key tidak dikenal atau bukan key Cognivo v2
402	insufficient_credits	penggunaan berbayar: saldo kredit Cognivo Anda tidak cukup untuk panggilan itu (tidak ada yang ditagih)
402	payment_required	endpoint ini butuh akses berbayar pada key ini dan tidak ada jalur pembayaran valid yang menutup panggilan itu (tidak ada yang ditagih)
403	access_required	key tidak punya hibah akses untuk endpoint intelijen live - ajukan akses trial, partner, berbayar, atau enterprise
403	sandbox_limited	key sandbox (cogv_test_) mencoba panggilan live di luar jatah demo yang diaktifkan admin
403	trial_expired	akses trial key ini sudah kedaluwarsa
403	trial_exhausted	jatah trial key ini sudah terpakai habis
403	endpoint_denied	hibah akses key ini tidak mencakup endpoint spesifik ini
403	suspended_key	key ditangguhkan oleh admin
403	revoked_api_key	key sudah dicabut atau digantikan lewat rotasi
403	project_disabled	proyek pemiliknya ditangguhkan atau diarsipkan
403	scope_denied	key tidak punya scope yang dibutuhkan endpoint ini
403	origin_denied	allow-list Origin/IP dikonfigurasi pada key dan tidak cocok
404	public_api_disabled	API publik sedang dimatikan sementara
422	insufficient_data (dan sejenisnya)	alat berjalan tetapi tidak bisa memverifikasi hasil yang adil - Anda tidak ditagih
429	rate_limited	anggaran per jam habis
500	internal_error	kegagalan tak terduga - sertakan request_id saat menghubungi dukungan
503	billing_unavailable / unavailable	gangguan dependensi sementara - coba lagi nanti, tidak ada yang ditagih

Setiap respons membawa request_id (juga meta.request_id saat sukses). Simpan; tim dukungan bisa melacak panggilan darinya.

Error umum dan cara memperbaikinya

• 401 missing_api_key - key tidak pernah sampai ke kami. Kirim di header X-API-Key (nama persis) atau sebagai Authorization: Bearer YOUR_API_KEY, dan periksa apakah proxy atau framework tidak menghapus header itu.
• 401 invalid_api_key - key tidak dikenali. Key harus diawali cogv_live_ atau cogv_test_; pastikan Anda menyalin key secara utuh tanpa spasi di sekelilingnya. Kalau yang asli hilang, rotasi key di portal dan gunakan yang baru.
• 403 revoked_api_key - key ini sudah dicabut atau digantikan lewat rotasi. Ambil key terbaru dari portal; yang lama tidak akan pernah berfungsi lagi.
• 403 scope_denied - key berfungsi, tetapi tidak punya scope yang dibutuhkan endpoint ini (misalnya security:read untuk wallet/approvals). Ubah scope key atau buat key dengan scope yang tepat; lihat Autentikasi dan API key.
• 403 origin_denied - key punya allow-list Origin atau IP dan permintaan ini datang dari tempat lain. Panggil dari origin/IP yang ada di allow-list, atau kosongkan daftarnya pada key.
• 403 access_required - key valid tetapi tidak punya hibah akses untuk endpoint intelijen live. Ajukan akses trial, partner, berbayar, atau enterprise dari portal Developer; tanpa itu panggilan tidak pernah berjalan (dan tidak pernah menagih).
• 403 sandbox_limited - key sandbox (cogv_test_) mencoba panggilan intelijen live di luar jatah demonya. Minta admin mengaktifkan jatah live-demo untuk key itu, atau gunakan live key yang punya akses.
• 403 trial_expired / trial_exhausted - trial Anda sudah berakhir (waktu atau jatah). Ajukan perpanjangan atau beralih ke akses berbayar, partner, atau enterprise.
• 403 endpoint_denied - hibah akses Anda mencakup endpoint lain tetapi bukan yang ini (akses per endpoint umum pada hibah partner/enterprise). Ajukan akses untuk endpoint ini.
• 403 suspended_key - key ditangguhkan oleh admin. Hubungi dukungan dari dApp dengan menyertakan request_id Anda.
• 402 payment_required - panggilan ini butuh akses berbayar pada key ini. Isi ulang kredit Cognivo atau ajukan mode akses yang mencakup endpoint itu; tidak ada yang ditagih.
• 429 rate_limited - Anda menghabiskan anggaran key ini. Pelankan, tambahkan antrean sisi klien dengan backoff, atau ajukan mode akses yang lebih tinggi. Ingat, key sandbox cogv_test_ dibatasi 25 permintaan/jam dan 100/hari; akses metadata free dibatasi 60/jam dengan batas burst 1/detik.
• 400 invalid_chain - chain harus eth, base, atau bsc. Nama seperti ethereum atau chain id numerik seperti 8453 tidak diterima.
• 400 invalid_address / invalid_wallet / invalid_token - kirim alamat lengkap 0x + 40 karakter heksadesimal. Nama ENS dan simbol token tidak diresolusi oleh API.
• 422 insufficient_data - bukan gangguan dan bukan salah Anda: alat berjalan tetapi tidak bisa memverifikasi jawaban yang adil (misalnya wallet/pnl pada dompet tanpa transaksi berharga pada token itu). Anda tidak pernah ditagih untuk 422; coba dompet/token lain atau pertanyaan yang lebih luas.
• 404 public_api_disabled - API publik sedang dimatikan sementara, bukan URL yang salah. Coba lagi nanti atau periksa kanal pengumuman.

Akses, penagihan, dan kredit

Developer API dikontrol aksesnya selama akses awal. Key free bisa mengeksplorasi: membaca dokumentasi, memanggil GET /v1/api/health, memeriksa dirinya lewat GET /v1/api/me, dan melakukan panggilan sandbox/demo terbatas. Endpoint intelijen live membutuhkan akses trial, partner, berbayar, atau enterprise; tanpa itu endpoint mengembalikan error yang jelas (access_required, trial_expired, payment_required, dan sejenisnya) alih-alih berjalan gratis.

• Penggunaan berbayar ditagih dalam kredit Cognivo per panggilan yang sukses, dari saldo kredit Cognivo Anda yang sudah ada (kredit yang sama dengan Chat/Telegram), dibelanjakan oleh akun pemilik proyek. Kegagalan, timeout, hasil kosong, dan error tidak ditagih.
• Tagihan bersifat idempoten - permintaan yang diulang atau terduplikasi tidak bisa menagih dua kali.
• Key sandbox (cogv_test_) untuk pengujian integrasi: dibatasi 25 permintaan/jam dan 100/hari, dan hanya bisa menjalankan jatah live-demo kecil saat diaktifkan oleh admin.
• Akses trial diberikan oleh admin, terbatas dan bisa kedaluwarsa.
• Enterprise bersifat kustom: harga, batas lebih tinggi, dan akses per endpoint - ajukan akses dari dApp.

Biaya kredit per endpoint (berlaku untuk penggunaan berbayar; ditampilkan demi transparansi):

Endpoint	Kredit per panggilan sukses
intel/liquidity	2
intel/risk	2
wallet/approvals	2
intel/why-down	3
intel/team-wallets	5
wallet/exact-movements	5
wallet/pnl	10
health, me	gratis
discover	gratis, dengan batas laju yang ketat

Bukan nasihat keuangan

Hasil API adalah sinyal intelijen on-chain, bukan nasihat investasi, dan tidak adanya red flag bukan bukti keamanan. Selalu lakukan riset Anda sendiri.