Batas Laju, Kesalahan, dan Penagihan

Halaman ini adalah referensi untuk tiga hal yang menghentikan sebuah integrasi bekerja: kehabisan permintaan, mendapat kesalahan, dan kehabisan kredit. Halaman ini juga menunjukkan dari mana Anda bisa memantau ketiganya di akun Anda.

Bukalah halaman ini ketika sebuah panggilan yang kemarin berfungsi mengembalikan kode yang tidak Anda kenali, ketika Anda memperkirakan berapa banyak permintaan yang bisa dilakukan aplikasi Anda, atau ketika Anda ingin tahu persis berapa biaya sebuah panggilan sebelum Anda merilisnya.

Batas laju

Batas ditetapkan per key, berdasarkan mode akses:

Mode akses	Batas
live berbayar: basic (bawaan untuk setiap live key baru)	1,000 permintaan/jam
live berbayar: premium (ditetapkan admin)	5,000 permintaan/jam
live berbayar: pro (ditetapkan admin)	15,000 permintaan/jam
partner atau enterprise	dikonfigurasi admin
key sandbox cogv_test_ mana pun	25 permintaan/jam, 100/hari, 1/detik
permukaan metadata (health, me, discover) dengan key valid mana pun	60 permintaan/jam, 1/detik

Live key baru dimulai pada basic tanpa tahap persetujuan. Premium dan pro ditetapkan oleh Cognivo, sedangkan batas partner dan enterprise ditetapkan per kesepakatan. Header RateLimit-* standar dikembalikan pada setiap panggilan, sehingga Anda bisa melihat sisa anggaran tanpa menebak. Ketika anggaran habis, Anda mendapat 429 rate_limited dengan header Retry-After yang memberi tahu kapan harus mencoba lagi.

Memantau penggunaan Anda

Masuk ke dApp, buka Account di sidebar kiri, pilih Developers, lalu buka tab Usage.

Tab Usage di halaman Developers, ditampilkan untuk key yang belum pernah dipakai.Perbesar gambar

Pemilih rentang di bagian atas berganti antara Last 24 hours, Last 7 days, dan Last 30 days. Di sebelahnya, sebuah chip menampilkan saldo kredit Anda dan chip lain menampilkan tingkatan laju serta batas per jam yang berlaku untuk key Anda. Di bawahnya, lima penghitung memecah rentang tersebut menjadi Requests, Successful, Errors, Rate limited, dan Credits used, dan kartu Outcome breakdown membagi rentang yang sama menjadi tiga bagian.

Quoted vs charged adalah panel yang harus dibaca sebelum Anda mengkhawatirkan tagihan. Dalam kata-kata produk itu sendiri, "Quoted is the list price. Charged is what actually came out of your balance." Kedua angka itu tidak selalu sama, karena panggilan yang gagal, panggilan yang ditolak, dan jawaban kosong yang jujur tetap dikutip tetapi tidak pernah dibebankan.

Request history mencantumkan panggilan satu per satu dan bisa disaring berdasarkan key, endpoint, dan status. Dua keadaan kosong memiliki arti berbeda. "No requests match these filters." berarti ada panggilan dalam rentang ini tetapi tidak ada yang cocok dengan saringan Anda, jadi longgarkan saringannya. "No usage in this window yet." berarti tidak ada panggilan dari key mana pun milik Anda yang masuk dalam rentang ini sama sekali. Keduanya bukan kesalahan, dan keduanya tidak berarti ada panggilan yang hilang. Jika Anda mengharapkan trafik tetapi melihat nol, pastikan aplikasi Anda memakai key yang Anda kira, dan longgarkan rentangnya.

Kode kesalahan

HTTP	error	Arti
400	bad_request / invalid_chain / invalid_address / invalid_wallet / invalid_token	Masukan tidak berbentuk benar. chain harus eth, base, atau bsc, dan alamat harus 0x ditambah 40 karakter heksadesimal.
401	missing_api_key	Tidak ada X-API-Key atau token Bearer yang disertakan.
401	invalid_api_key	Key tidak dikenal, atau bukan key Cognivo v2.
402	payment_required	Kredit Cognivo tidak cukup untuk panggilan ini. Tidak ada biaya yang dikenakan.
403	access_required	Key lawas yang hanya untuk metadata mencoba panggilan live.
403	sandbox_limited	Key sandbox (cogv_test_) mencoba panggilan intelijen live.
403	trial_expired	Jatah trial opsional pada key telah kedaluwarsa.
403	trial_exhausted	Jatah trial opsional pada key telah habis terpakai.
403	endpoint_denied	Kesepakatan akses key tidak mencakup endpoint ini.
403	chain_denied	Key dibatasi pada jaringan tertentu dan permintaan ini menyebut jaringan lain. Ditolak sebelum panggilan ke hulu mana pun dan sebelum jatah mana pun terpakai.
403	key_expired	Masa berlaku key sudah lewat. Key ditolak di mana pun, termasuk GET /v1/api/me.
403	suspended_key	Key ditangguhkan dan tidak bisa dieksekusi. Portal menampilkan alasannya.
403	revoked_api_key	Key telah dicabut atau digantikan lewat rotate.
403	project_disabled	Proyek pemiliknya ditangguhkan atau diarsipkan.
403	scope_denied	Key tidak memiliki scope yang dibutuhkan endpoint ini.
403	origin_denied	Daftar izin Origin atau IP dikonfigurasi pada key dan permintaan ini tidak cocok dengannya.
404	public_api_disabled	API publik sedang dimatikan sementara.
422	insufficient_data dan sejenisnya	Alat berjalan tetapi tidak bisa mendasarkan hasil yang wajar. Anda tidak dikenakan biaya.
429	rate_limited	Anggaran laju habis. Respons membawa Retry-After.
500	internal_error	Kegagalan tak terduga. Sertakan request_id saat Anda menghubungi Support.
503	pricing_mismatch / billing_unavailable / billing_commit_failed / unavailable	Gangguan penagihan atau dependensi yang jarang terjadi. Tidak ada biaya yang dikenakan, jadi coba lagi.

Setiap respons membawa request_id, dan respons yang berhasil mengulanginya sebagai meta.request_id. Simpanlah. Tim Support bisa melacak satu panggilan dari nilai itu saja.

Kesalahan umum dan cara memperbaikinya

• 401 missing_api_key. Key tidak pernah sampai ke kami. Kirim key di header X-API-Key, dieja persis, atau sebagai Authorization: Bearer YOUR_API_KEY, dan pastikan tidak ada proxy yang membuang header itu.
• 401 invalid_api_key. Key harus diawali cogv_live_ atau cogv_test_. Salin key secara utuh tanpa spasi di sekelilingnya. Jika Anda kehilangan yang asli, lakukan rotate pada key di portal lalu gunakan yang baru.
• 402 payment_required. Isi ulang di halaman Billing Cognivo Anda, lalu coba lagi. Tidak ada biaya yang dikenakan. GET /v1/api/me menampilkan saldo Anda saat ini.
• 403 revoked_api_key. 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. Lihat Autentikasi dan API key.
• 403 origin_denied. Panggil dari origin atau IP yang ada di daftar izin, atau kosongkan daftar pada key tersebut.
• 403 access_required. Ini adalah key lawas yang hanya untuk metadata dari sebelum era penagihan mandiri. Buat live key baru di portal.
• 403 sandbox_limited. Key sandbox untuk pengujian dan tidak bisa menjalankan intelijen live. Buat sebuah live key.
• 403 chain_denied. Periksa allowed_chains pada GET /v1/api/me. Nilai null di sana berarti tanpa pembatasan. Tidak ada biaya yang dikenakan.
• 403 trial_expired atau trial_exhausted. Jatah evaluasi opsional telah berakhir. Anda tidak memerlukan trial, jadi beralihlah ke live key biasa.
• 403 endpoint_denied. Kesepakatan Anda mencakup endpoint lain tetapi bukan yang ini. Mintalah agar endpoint ini disertakan.
• 403 suspended_key. Portal menampilkan alasannya. Hubungi Support dari dApp dengan request_id Anda jika alasannya kurang jelas.
• 429 rate_limited. Patuhi header Retry-After dan tambahkan antrean di sisi klien dengan backoff, atau tanyakan tentang batas yang lebih tinggi.
• 400 invalid_chain. Gunakan eth, base, atau bsc. Nama seperti ethereum dan id chain berupa angka tidak diterima.
• 400 invalid_address, invalid_wallet, invalid_token. Kirim alamat lengkap 0x ditambah 40 karakter heksadesimal. API tidak mengurai nama ENS atau simbol token.
• 422 insufficient_data. Bukan gangguan layanan dan bukan kesalahan Anda. Alat berjalan tetapi tidak bisa mendasarkan jawaban yang wajar, misalnya wallet/pnl pada dompet tanpa perdagangan berharga pada token itu. Artinya Cognivo tidak bisa memverifikasi jawabannya, bukan berarti jawabannya nol. Anda tidak pernah dikenakan biaya untuk 422.
• 404 public_api_disabled. API publik sedang dimatikan sementara. Ini bukan URL yang salah, jadi coba lagi nanti.

Kredit dan penagihan

Live key bersifat mandiri. Tidak ada pengajuan dan tidak ada langganan. Live key baru langsung berfungsi, dan setiap panggilan yang berhasil memotong harga kredit endpoint tersebut dari saldo kredit Cognivo milik pemilik proyek, yaitu kredit yang sama dengan yang dipakai Chat dan dApp. Setiap akun mendapat 5 kredit gratis per hari, dan kredit itu disetel ulang pada tengah malam UTC. Penagihan untuk panggilan Developer API dimatikan hari ini, jadi panggilan yang berhasil tidak memotong apa pun dan saldo Anda tidak berubah.

Harga setiap endpoint dalam kredit dicetak di sebelahnya pada tab Endpoints di halaman Developers, dan endpoint gratis diberi label Free di sana. Bacalah harganya dari portal alih-alih menuliskannya langsung di kode.

• Panggilan yang gagal tidak pernah dikenakan biaya. Kesalahan, timeout, panggilan yang ditolak, dan batas laju tidak memakan biaya.
• Panggilan yang berhasil dibebankan tepat satu kali, sehingga percobaan ulang aman.
• Hasil kosong yang jujur bersifat gratis. Respons 422, dan daftar wallet/approvals yang kosong, adalah jawaban yang sah dan tidak dikenakan biaya.
• Kehabisan kredit memberi Anda 402 payment_required tanpa biaya apa pun. Isi ulang di dApp, lalu coba lagi.
• Key sandbox (cogv_test_) tidak pernah dikenakan biaya dan tidak bisa menjalankan intelijen live.
• Key yang ditangguhkan dan proyek yang dinonaktifkan tidak bisa mengeksekusi apa pun dan tidak pernah dikenakan biaya.
• Enterprise adalah jalur pengajuan untuk harga khusus, batas khusus, dan volume, dan Anda mengajukannya dari dApp.

Membaca hasil dengan jujur

Hasil API menggambarkan apa yang diperiksa Cognivo dan apa yang ditemukannya di chain. Hasil yang bersih bukan bukti bahwa sebuah token atau dompet aman, dan hasil yang ditandai bukan bukti penipuan. Field yang hilang atau tidak tersedia berarti Cognivo tidak bisa memverifikasi butir tersebut, bukan berarti tidak ada apa-apa di sana. Perlakukan setiap respons sebagai satu masukan bagi riset Anda sendiri.

Langkah berikutnya

Cari parameter, scope, dan contoh respons di Referensi endpoint, perketat key Anda dengan Autentikasi dan API key, atau lihat cara kerja kredit di bagian produk lainnya di Billing dan kredit.