Hız Limitleri, Hatalar ve Faturalandırma

Bu sayfa, bir entegrasyonun çalışmasını durduran üç şeyin referansıdır: istek hakkının tükenmesi, hata alınması ve kredilerin bitmesi. Ayrıca bu üçünü hesabınızdan nereden izleyeceğinizi de gösterir.

Dün çalışan bir çağrı tanımadığınız bir kod döndürdüğünde, uygulamanızın kaç istek yapabileceğini hesaplarken ya da yayına almadan önce bir çağrının tam olarak ne kadara mal olacağını bilmek istediğinizde bu sayfaya başvurun.

Hız limitleri

Limitler anahtar başına, erişim moduna göre belirlenir:

Erişim modu	Limit
canlı ücretli: basic (her yeni canlı anahtar için varsayılan)	saatte 1.000 istek
canlı ücretli: premium (yönetici tarafından atanır)	saatte 5.000 istek
canlı ücretli: pro (yönetici tarafından atanır)	saatte 15.000 istek
partner veya enterprise	yönetici tarafından yapılandırılır
herhangi bir cogv_test_ sandbox anahtarı	saatte 25 istek, günde 100, saniyede 1
metadata yüzeyi (health, me, discover), geçerli herhangi bir anahtarla	saatte 60 istek, saniyede 1

Yeni bir canlı anahtar, onay adımı olmadan basic ile başlar. Premium ve pro, Cognivo tarafından atanır; partner ve enterprise limitleri ise anlaşmaya göre belirlenir. Standart RateLimit-* başlıkları her çağrıda geri döner, böylece kalan bütçenizi tahmin etmeden görebilirsiniz. Bütçe tükendiğinde, ne zaman yeniden deneyeceğinizi söyleyen bir Retry-After başlığıyla birlikte 429 rate_limited alırsınız.

Kullanımınızı izleme

dApp'te oturum açın, sol kenar çubuğunda Account bölümünü açın, Developers seçin, ardından Usage sekmesini açın.

Developers sayfasındaki Usage sekmesi, henüz kullanılmamış bir anahtar için gösteriliyor.Görseli büyüt

Üstteki pencere seçicisi Last 24 hours, Last 7 days ve Last 30 days arasında geçiş yapar. Yanında bir çip kredi bakiyenizi, bir diğeri de anahtarlarınız için geçerli hız katmanını ve saatlik limiti gösterir. Bunun altında beş sayaç, seçilen pencereyi Requests, Successful, Errors, Rate limited ve Credits used olarak ayırır; Outcome breakdown kartı da aynı pencereyi üç şekilde böler.

Quoted vs charged, bir fatura konusunda endişelenmeden önce okumanız gereken paneldir. Ürünün kendi ifadesiyle, "Quoted is the list price. Charged is what actually came out of your balance." Bu iki sayı her zaman aynı değildir; çünkü başarısız çağrılar, reddedilen çağrılar ve dürüst boş yanıtlar fiyatlandırılır ama asla ücretlendirilmez.

Request history, tek tek çağrıları listeler ve anahtara, endpoint'e ve duruma göre filtrelenebilir. İki boş durum farklı anlamlara gelir. "No requests match these filters." ifadesi, bu pencerede çağrılar olduğunu ama hiçbirinin filtrenize uymadığını gösterir; filtreleri genişletin. "No usage in this window yet." ifadesi ise bu pencereye anahtarlarınızdan hiçbirinden çağrı gelmediği anlamına gelir. Bunların ikisi de hata değildir ve hiçbiri bir çağrının kaybolduğu anlamına gelmez. Trafik beklediğiniz halde sıfır görüyorsanız, uygulamanızın sandığınız anahtarı kullandığını kontrol edin ve pencereyi genişletin.

Hata kodları

HTTP	error	Anlamı
400	bad_request / invalid_chain / invalid_address / invalid_wallet / invalid_token	Hatalı biçimlendirilmiş girdi. chain değeri eth, base ya da bsc olmalıdır ve adresler 0x artı 40 onaltılık karakterden oluşmalıdır.
401	missing_api_key	X-API-Key ya da Bearer token sunulmadı.
401	invalid_api_key	Anahtar bilinmiyor ya da bir Cognivo v2 anahtarı değil.
402	payment_required	Bu çağrı için yeterli Cognivo kredisi yok. Hiçbir ücret kesilmedi.
403	access_required	Yalnızca metadata çağırabilen eski bir anahtar canlı çağrı denedi.
403	sandbox_limited	Bir sandbox (cogv_test_) anahtarı canlı istihbarat çağrısı denedi.
403	trial_expired	Anahtarın isteğe bağlı deneme hakkının süresi doldu.
403	trial_exhausted	Anahtarın isteğe bağlı deneme hakkı tamamen kullanıldı.
403	endpoint_denied	Anahtarın erişim düzenlemesi bu endpoint'i kapsamıyor.
403	chain_denied	Anahtar belirli ağlarla sınırlı ve bu istek farklı bir ağ belirtti. Herhangi bir yukarı akış çağrısından ve herhangi bir hak kullanımından önce reddedilir.
403	key_expired	Anahtarın son kullanma tarihi geçti. GET /v1/api/me dahil her yerde reddedilir.
403	suspended_key	Anahtar askıya alınmış ve çalıştırılamaz. Portal nedenini gösterir.
403	revoked_api_key	Anahtar iptal edildi ya da döndürülerek devre dışı kaldı.
403	project_disabled	Sahibi olan proje askıya alınmış ya da arşivlenmiş.
403	scope_denied	Anahtar, bu endpoint'in gerektirdiği kapsama (scope) sahip değil.
403	origin_denied	Anahtarda bir Origin ya da IP izin listesi yapılandırılmış ve bu istek bununla eşleşmedi.
404	public_api_disabled	Herkese açık API geçici olarak kapatılmış.
422	insufficient_data ve benzerleri	Araç çalıştı ama adil bir sonucu temellendiremedi. Ücretlendirilmezsiniz.
429	rate_limited	Hız bütçesi tükendi. Yanıt Retry-After taşır.
500	internal_error	Beklenmedik hata. Destekle iletişime geçerken request_id bilgisini ekleyin.
503	pricing_mismatch / billing_unavailable / billing_commit_failed / unavailable	Nadir görülen bir faturalandırma ya da bağımlılık aksaklığı. Hiçbir ücret kesilmedi, yeniden deneyin.

Her yanıt request_id taşır ve başarılı yanıtlar bunu meta.request_id olarak yineler. Bu değeri saklayın. Destek ekibi tek bir çağrıyı bu tek değerden 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 olarak doğru yazımıyla ya da Authorization: Bearer YOUR_API_KEY biçiminde gönderin ve hiçbir proxy'nin başlığı kaldırmadığını kontrol edin.
• 401 invalid_api_key. Anahtar cogv_live_ ya da cogv_test_ ile başlamalıdır. Anahtarın tamamını çevresinde boşluk olmadan kopyalayın. Orijinali kaybettiyseniz anahtarı portalda döndürün ve yenisini kullanın.
• 402 payment_required. Cognivo faturalandırma sayfanızdan kredi yükleyin, sonra yeniden deneyin. Hiçbir ücret kesilmedi. GET /v1/api/me güncel bakiyenizi gösterir.
• 403 revoked_api_key. Portaldaki en yeni anahtarı alın. Eskisi bir daha asla çalışmayacak.
• 403 scope_denied. Anahtar çalışıyor ama bu endpoint'in gerektirdiği kapsama sahip değil; örneğin wallet/approvals için security:read. Bkz. Kimlik doğrulama ve API anahtarları.
• 403 origin_denied. İzin listesindeki bir origin ya da IP üzerinden çağrı yapın ya da anahtardaki listeleri temizleyin.
• 403 access_required. Bu, self servis faturalandırmadan önceki, yalnızca metadata çağırabilen eski bir anahtardır. Portalda yeni bir canlı anahtar oluşturun.
• 403 sandbox_limited. Sandbox anahtarları test içindir ve canlı istihbarat çalıştıramaz. Canlı bir anahtar oluşturun.
• 403 chain_denied. GET /v1/api/me üzerinde allowed_chains değerini kontrol edin. Orada null olması kısıtlama olmadığı anlamına gelir. Hiçbir ücret kesilmedi.
• 403 trial_expired ya da trial_exhausted. İsteğe bağlı değerlendirme hakkı sona erdi. Denemeye ihtiyacınız yok, sıradan bir canlı anahtara geçin.
• 403 endpoint_denied. Düzenlemeniz başka endpoint'leri kapsıyor ama bunu kapsamıyor. Kapsama dahil edilmesini talep edin.
• 403 suspended_key. Portal nedenini gösterir. Neden belirsizse request_id bilginizle birlikte dApp üzerinden destekle iletişime geçin.
• 429 rate_limited. Retry-After başlığına uyun ve istemci tarafında geri çekilmeli (backoff) bir kuyruk ekleyin ya da daha yüksek bir limit talep edin.
• 400 invalid_chain. eth, base ya da bsc kullanın. ethereum gibi adlar ve sayısal zincir kimlikleri kabul edilmez.
• 400 invalid_address, invalid_wallet, invalid_token. 0x artı 40 onaltılık karakterden oluşan tam bir adres gönderin. API, ENS adlarını ya da token sembollerini çözümlemez.
• 422 insufficient_data. Bu bir kesinti değildir ve sizin hatanız da değildir. Araç çalıştı ama adil bir yanıtı temellendiremedi; örneğin o token'da fiyatlanmış işlemi olmayan bir cüzdanda wallet/pnl. Bu, karın sıfır olduğu anlamına gelmez; Cognivo'nun yanıtı doğrulayamadığı anlamına gelir. Bir 422 için asla ücretlendirilmezsiniz.
• 404 public_api_disabled. Herkese açık API geçici olarak kapatılmıştır. Bu yanlış bir URL değildir, daha sonra tekrar deneyin.

Krediler ve faturalandırma

Canlı anahtarlar self servistir. Başvuru ya da abonelik yoktur. Yeni bir canlı anahtar hemen çalışır ve her başarılı çağrı, o endpoint'in kredi fiyatını proje sahibinin Cognivo kredi bakiyesinden düşer; bunlar Sohbet ve dApp'in kullandığı kredilerin aynısıdır. Her hesap günde 5 ücretsiz kredi alır ve bunlar UTC gece yarısında sıfırlanır. Developer API çağrıları için ücretlendirme bugün kapalıdır, bu yüzden başarılı bir çağrı hiçbir şey düşmez ve bakiyeniz değişmez.

Her endpoint'in kredi cinsinden fiyatı, Developers sayfasının Endpoints sekmesinde yanında yazar ve ücretsiz endpoint'ler orada Free olarak etiketlenir. Fiyatı koda sabitlemek yerine portaldan okuyun.

• Başarısız çağrılar asla ücretlendirilmez. Hatalar, zaman aşımları, reddedilen çağrılar ve hız limitleri hiçbir şeye mal olmaz.
• Başarılı bir çağrı tam olarak bir kez ücretlendirilir, bu yüzden yeniden denemeler güvenlidir.
• Dürüst boş sonuçlar ücretsizdir. Bir 422 ve boş bir wallet/approvals listesi geçerli yanıtlardır ve ücretlendirilmez.
• Kredi bittiğinde hiçbir ücret kesilmeden 402 payment_required alırsınız. dApp'te kredi yükleyin, sonra yeniden deneyin.
• Sandbox (cogv_test_) anahtarları asla ücretlendirilmez ve canlı istihbarat çalıştıramaz.
• Askıya alınmış anahtarlar ve devre dışı bırakılmış projeler hiçbir şey çalıştıramaz ve asla ücretlendirilmez.
• Enterprise, özel fiyatlandırma, özel limitler ve hacim için talep yoludur ve bunu dApp üzerinden talep edersiniz.

Sonuçları dürüstçe okumak

API sonuçları, Cognivo'nun neyi kontrol ettiğini ve zincir üzerinde ne bulduğunu anlatır. Temiz bir sonuç, bir token'ın ya da cüzdanın güvenli olduğunun kanıtı değildir; işaretlenmiş bir sonuç da dolandırıcılığın kanıtı değildir. Eksik ya da kullanılamayan bir alan, orada hiçbir şey olmadığı anlamına gelmez; Cognivo'nun o öğeyi doğrulayamadığı anlamına gelir. Her yanıtı kendi araştırmanız için bir girdi olarak değerlendirin.

Sonraki adımlar

Parametreleri, kapsamları ve örnek yanıtları Endpoint referansında arayın, anahtarlarınızı Kimlik doğrulama ve API anahtarları ile sıkılaştırın ya da kredilerin ürünün geri kalanında nasıl işlediğini Billing ve Krediler sayfasında görün.