API Hata Kodları ve İstek Sınırları

24s Hacim—Açık pozisyon—24s Likidasyon$1.20B 24s Long/Short—BTC Hakimiyeti—ETH Hakimiyeti—

Uygulama

Dil ▾

₺ TRY ▾

Hatalar ve istek sınırları

Her uç nokta hataları aynı yapıda, makinece okunabilir bir kod ve bir istek kimliğiyle bildirir.

Hata yanıtı

Başarısız bir çağrı success: false döndürür. code kararlıdır ve programlar içindir; error insanlar için yazılmış kısa bir İngilizce mesajdır; request_id ise çağrıyı günlüklerimizde tanımlar. Sorun bir girdiden kaynaklanıyorsa param hatalı parametrenin adını verir.

Gerçek örnekler

Bunlar, bu sayfa oluşturulurken API'den alınan canlı yanıtlardır.

Zorunlu parametre eksik · GET /api/sd/oi · HTTP 400

{
  "success": false,
  "error": "coin required",
  "code": "INVALID_PARAM",
  "request_id": "cb-mwefrp2c-a0018ab25e"
}

Bilinmeyen uç nokta · HTTP 404

{
  "success": false,
  "code": "NOT_FOUND",
  "error": "unknown endpoint: GET /api/this-endpoint-does-not-exist",
  "request_id": "cb-mwefrp2c-1eb1f24b69"
}

Hata kodları

Kod	HTTP	Anlamı	Ne yapmalı
INVALID_PARAM	400	Zorunlu bir parametre eksik ya da bir değer kabul edilmiyor. Biliniyorsa `param` parametrenin adını verir.	Değiştirmeden yeniden denemeyin; isteği düzeltin.
UNAUTHORIZED	401	`CB-API-KEY` başlığı gönderildi, ancak anahtar bilinmiyor veya iptal edilmiş. Herkese açık veriler anahtar gerektirmez; başlığı kaldırın veya geçerli bir anahtar kullanın.	Değiştirmeden yeniden denemeyin.
FORBIDDEN	403	Bu rota herkese açık API'nin parçası değildir (dahilî veya yalnızca hesaba özel).	Yeniden denemeyin.
NOT_FOUND	404	Bilinmeyen rota ya da istenen coin / borsa / fon yok.	Yeniden denemeyin; yolu ve tanımlayıcıları katalogla karşılaştırarak kontrol edin.
RATE_LIMITED	429	Dakika başına sınırdan fazla istek gönderildi. `Retry-After`, beklenecek saniye sayısını verir.	`Retry-After` süresi kadar bekleyin, ardından artan beklemeyle yeniden deneyin.
INTERNAL	500	Beklenmeyen sunucu hatası. Mesaj bilinçli olarak geneldir; hatayı bildirirken `request_id` değerini belirtin.	Birkaç saniye sonra bir kez yeniden deneyin; sorun sürerse istek kimliğiyle birlikte bildirin.
UPSTREAM_FAILED	503	Bu uç noktanın arkasındaki veri kaynağı zamanında yanıt vermedi. Yerine eskimiş veya ikame rakamlar döndürülmez.	Artan beklemeyle yeniden deneyin; durum sayfasını kontrol edin.
UNAVAILABLE	501 / 503	Veri kümesi geçici olarak hazır değil (önbellek ısınıyor) ya da uç noktanın henüz yasal bir herkese açık kaynağı yok.	Daha sonra yeniden deneyin; katalog, tasarım gereği mevcut olmayan uç noktaları işaretler.
REQUEST_FAILED	200	Bazı eski uç noktalar HTTP 200 ile `success: false` yanıtı verir. Yalnızca HTTP durumunu değil, her zaman `success` değerini de kontrol edin.	Mesaja bağlıdır; başarısız bir istek olarak ele alın.

Eski uç noktalar, bulunamayan bir öğe için success: false ve REQUEST_FAILED koduyla HTTP 200 döndürebilir. Her yanıtta success değerini kontrol edin.

İstek kimliği

Her yanıt bir X-Request-Id başlığı taşır. Başarısız yanıtlar bunu gövdede request_id olarak yineler. Kısa süreli edge önbelleğinden sunulan yanıtlar, kendilerini üreten isteğin kimliğini yineler; bu nedenle art arda çağrılarda aynı kimliği görmeniz, önbelleğe alınmış bir kopya aldığınız anlamına gelir.

İstek sınırları

Sınırlar dakika bazında uygulanır: anonim çağrılarda IP adresi başına, geçerli bir CB-API-KEY başlığı gönderildiğinde anahtar başına. Sınır dakikada 1200 istektir. /api/coin-icon altındaki simge istekleri sayılmaz.

İstek sınırı başlıkları

Ad	Açıklama
X-Request-Id	Bu isteğin tanımlayıcısı. Hata bildirimlerinde belirtin.
X-RateLimit-Limit	Geçerli bir dakikalık pencerede izin verilen istek sayısı.
X-RateLimit-Remaining	Geçerli pencerede kalan istek sayısı.
X-RateLimit-Reset	Pencerenin sıfırlanacağı an; saniye cinsinden Unix zamanı.
Retry-After	HTTP 429 ile gönderilir: yeniden denemeden önce beklenecek saniye sayısı.
X-Cache	Sunucu tarafı yanıt önbelleği için HIT, STALE veya MISS.

Sınırı aştığınızda

API, RATE_LIMITED koduyla HTTP 429 yanıtı verir. Retry-After başlığında belirtilen saniye kadar bekleyip yeniden deneyin. Bir uç noktayı önbellek TTL'sinden daha sık sorgulamak aynı önbellek yanıtını döndürür; bu yüzden sorgulama aralığınızı her referans sayfasında gösterilen TTL'ye göre ayarlayın.

Artan beklemeyle yeniden deneme

JavaScript

async function getJson(url, tries = 4) {
  for (let i = 0; i < tries; i++) {
    const res = await fetch(url);
    if (res.status === 429 || res.status >= 500) {
      const wait = Number(res.headers.get("Retry-After")) || 2 ** i;
      await new Promise((r) => setTimeout(r, wait * 1000));
      continue;
    }
    const body = await res.json();
    if (body.success === false) {
      throw new Error(body.code + ": " + body.error + " (" + body.request_id + ")");
    }
    return body;
  }
  throw new Error("gave up after " + tries + " attempts");
}

Veri yokluğu hata değildir

Parametreler geçerli olduğu hâlde veri için yasal ve herkese açık bir kaynak yoksa çağrı HTTP 200 ile başarılı olur: değer alanları null, meta.quality ise UNAVAILABLE olur ve coverage.unavailable nedeni listeler. Bunu tire olarak gösterin. 0'a dönüştürmeyin.

Eskimiş veri

Bir toplayıcı geride kalırsa uç noktalar, depolanan son değerleri kullanılabilirlik penceresini aşana kadar meta.is_stale: true ile sunmaya devam eder; sonrasında bu değerler toplu hesaplardan çıkarılır ve coverage.stale_excluded içinde listelenir.