Hız limitleri, hatalar ve faturalandırma

Hız limitleri

Limitler anahtar başına ve erişim moduna göredir:

Erişim modu	Limit
free (üst veri: health, me, discover)	saatte 60 istek, saniyede 1 anlık patlama (burst) sınırıyla
basic (ücretli, devreye alındığında)	saatte 1,000 istek
premium (ücretli, devreye alındığında)	saatte 5,000 istek
pro (ücretli, devreye alındığında)	saatte 15,000 istek
iş ortağı / kurumsal	yönetici tarafından yapılandırılır
herhangi bir cogv_test_ sandbox anahtarı	saatte 25 ve günde 100 istek

Yeni anahtarlar yalnızca ücretsiz üst veri erişimiyle başlar. Deneme erişimi yönetici tarafından verilir, sınırlıdır ve süresi dolar; iş ortağı ve kurumsal limitler anlaşma başına yapılandırılır - dApp üzerinden erişim talep edin. Standart RateLimit-* başlıkları döndürülür; limit tükendiğinde 429 rate_limited alırsınız.

Hata kodları

HTTP	error	Anlamı
400	bad_request / invalid_chain / invalid_address / invalid_wallet / invalid_token	hatalı girdi; chain eth, base veya bsc olmalı; adresler 0x + 40 hex olmalı
401	missing_api_key	X-API-Key (veya Bearer) sunulmadı
401	invalid_api_key	anahtar bilinmiyor veya bir Cognivo v2 anahtarı değil
402	insufficient_credits	ücretli kullanım: Cognivo kredi bakiyeniz çağrıyı karşılayamıyor (hiçbir şey ücretlendirilmedi)
402	payment_required	bu endpoint bu anahtarda ücretli erişim gerektiriyor ve çağrıyı karşılayan geçerli bir ödeme yolu yok (hiçbir şey ücretlendirilmedi)
403	access_required	anahtarın canlı istihbarat endpoint'leri için erişim yetkisi yok - deneme, iş ortağı, ücretli veya kurumsal erişim talep edin
403	sandbox_limited	bir sandbox (cogv_test_) anahtarı, yönetici tarafından etkinleştirilmiş demo hakkının dışında canlı bir çağrı denedi
403	trial_expired	anahtarın deneme erişiminin süresi doldu
403	trial_exhausted	anahtarın deneme hakkı tamamen kullanıldı
403	endpoint_denied	anahtarın erişim yetkisi bu belirli endpoint'i kapsamıyor
403	suspended_key	anahtar bir yönetici tarafından askıya alındı
403	revoked_api_key	anahtar iptal edildi veya döndürülerek devre dışı bırakıldı
403	project_disabled	sahibi olan proje askıya alındı veya arşivlendi
403	scope_denied	anahtar bu endpoint'in gerektirdiği kapsamdan yoksun
403	origin_denied	anahtarda Origin/IP izin listesi yapılandırılmış ve eşleşmedi
404	public_api_disabled	herkese açık API geçici olarak kapalı
422	insufficient_data (ve benzerleri)	araç çalıştı ama adil bir sonucu temellendiremedi - ücretlendirilmezsiniz
429	rate_limited	saatlik kademe bütçesi tükendi
500	internal_error	beklenmeyen hata - destekle iletişime geçerken request_id ekleyin
503	billing_unavailable / unavailable	geçici bağımlılık kesintisi - daha sonra tekrar deneyin, hiçbir şey ücretlendirilmedi

Her yanıt bir request_id taşır (başarıda ayrıca meta.request_id). Saklayın; destek ekibi bir çağrıyı bununla izleyebilir.

Sık görülen hatalar ve çözümleri

• 401 missing_api_key - anahtar bize hiç ulaşmadı. Anahtarı X-API-Key başlığında (tam adıyla) veya Authorization: Bearer YOUR_API_KEY olarak gönderin ve bir proxy veya framework'ün başlığı silmediğini kontrol edin.
• 401 invalid_api_key - anahtar tanınmıyor. cogv_live_ veya cogv_test_ ile başlamalıdır; anahtarın tamamını, çevresinde boşluk olmadan kopyaladığınızı kontrol edin. Orijinali kaybettiyseniz portalda anahtarı döndürün ve yenisini kullanın.
• 403 revoked_api_key - bu anahtar iptal edildi veya döndürülerek devre dışı bırakıldı. Portaldan en yeni anahtarı alın; eskisi bir daha asla çalışmayacak.
• 403 scope_denied - anahtar çalışıyor ama bu endpoint'in gerektirdiği kapsamdan yoksun (örneğin wallet/approvals için security:read). Anahtarın kapsamlarını düzenleyin veya doğru kapsama sahip bir anahtar oluşturun; bkz. Kimlik doğrulama ve API anahtarları.
• 403 origin_denied - anahtarda bir Origin veya IP izin listesi var ve bu istek başka bir yerden geldi. İzin listesindeki bir origin/IP üzerinden çağırın veya anahtardaki listeleri temizleyin.
• 403 access_required - anahtar geçerli, ancak canlı istihbarat endpoint'leri için erişim yetkisi yok. Geliştirici portalından deneme, iş ortağı, ücretli veya kurumsal erişim talep edin; bu olmadan çağrı asla çalışmaz (ve asla ücretlendirilmez).
• 403 sandbox_limited - bir sandbox (cogv_test_) anahtarı, demo hakkının dışında canlı bir istihbarat çağrısı denedi. Bir yöneticiden anahtar için canlı demo hakkını etkinleştirmesini isteyin veya erişimi olan bir canlı anahtar kullanın.
• 403 trial_expired / trial_exhausted - denemeniz sona erdi (süre veya hak). Uzatma talep edin ya da ücretli, iş ortağı veya kurumsal erişime geçin.
• 403 endpoint_denied - erişim yetkiniz diğer endpoint'leri kapsıyor ama bunu kapsamıyor (endpoint'e özgü erişim, iş ortağı/kurumsal yetkilerde yaygındır). Bu endpoint için erişim talep edin.
• 403 suspended_key - anahtar bir yönetici tarafından askıya alındı. request_id değerinizle birlikte dApp üzerinden destekle iletişime geçin.
• 402 payment_required - bu çağrı bu anahtarda ücretli erişim gerektiriyor. Cognivo kredisi yükleyin veya endpoint'i kapsayan bir erişim modu talep edin; hiçbir şey ücretlendirilmedi.
• 429 rate_limited - bu anahtarın bütçesini tükettiniz. Yavaşlayın, backoff'lu istemci tarafı kuyruklama ekleyin veya daha yüksek bir erişim modu isteyin. cogv_test_ sandbox anahtarlarının saatte 25 ve günde 100 istekle sınırlı olduğunu unutmayın; ücretsiz üst veri erişimi, saniyede 1 anlık patlama sınırıyla saatte 60 istekle sınırlıdır.
• 400 invalid_chain - chain alanı eth, base veya bsc olmalıdır. ethereum gibi adlar veya 8453 gibi sayısal chain id'ler kabul edilmez.
• 400 invalid_address / invalid_wallet / invalid_token - tam bir 0x + 40 hex karakterlik adres gönderin. ENS adları ve token sembolleri API tarafından çözümlenmez.
• 422 insufficient_data - kesinti değil ve sizin hatanız da değil: araç çalıştı ama adil bir cevabı temellendiremedi (örneğin o token'da fiyatlandırılmış işlemi olmayan bir cüzdanda wallet/pnl). 422 için asla ücretlendirilmezsiniz; farklı bir cüzdan/token veya daha geniş bir soru deneyin.
• 404 public_api_disabled - herkese açık API geçici olarak kapalı, yanlış URL değil. Daha sonra tekrar deneyin veya duyuru kanalını kontrol edin.

Erişim, faturalandırma ve krediler

Developer API, erken erişim süresince erişim denetimlidir. Ücretsiz bir anahtar keşif yapabilir: dokümanları okuyabilir, GET /v1/api/health çağırabilir, GET /v1/api/me ile kendini inceleyebilir ve sınırlı sandbox/demo çağrıları yapabilir. Canlı istihbarat endpoint'leri deneme (trial), iş ortağı, ücretli veya kurumsal erişim gerektirir; bu olmadan ücretsiz çalışmak yerine net bir hata döndürürler (access_required, trial_expired, payment_required ve benzerleri).

• Ücretli kullanım, başarılı çağrı başına Cognivo kredisiyle, mevcut Cognivo kredi bakiyenizden (Chat/Telegram ile aynı krediler) ve proje sahibinin hesabından harcanarak ücretlendirilir. Hatalar, zaman aşımları, boş sonuçlar ve arızalar ücretlendirilmez.
• Ücretlendirmeler idempotenttir - yeniden denenen veya yinelenen bir istek çifte ücret oluşturamaz.
• Sandbox (cogv_test_) anahtarları entegrasyon testleri içindir: saatte 25 ve günde 100 istekle sınırlıdır ve yalnızca bir yönetici etkinleştirdiğinde küçük bir canlı demo hakkı çalıştırabilir.
• Deneme erişimi yönetici tarafından verilir, sınırlıdır ve süresi dolar.
• Kurumsal (Enterprise) özeldir: fiyatlandırma, daha yüksek limitler ve endpoint'e özgü erişim - dApp üzerinden erişim talep edin.

Endpoint başına kredi maliyetleri (ücretli kullanım için geçerlidir; şeffaflık için gösterilmiştir):

Endpoint	Başarılı çağrı başına kredi
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	ücretsiz
discover	ücretsiz, sıkı bir hız sınırıyla

Finansal tavsiye değildir

API sonuçları zincir üstü istihbarat sinyalleridir, yatırım tavsiyesi değildir ve kırmızı bayrak bulunmaması güvenliğin kanıtı değildir. Her zaman kendi araştırmanızı yapın.