PortGateby Portfoy

Hatalar ve hız limitleri

PortGate'in döndürdüğü her hata aynı JSON biçimine sahiptir ve bir istek kimliği taşır. Bu altı durum kodunu ele alın, her şeyi ele almış olun.

Hata biçimi

Tüm hatalar tek bir RFC-7807 tarzı gövdeyi paylaşır — bir HTTP durumu, makinece kararlı bir title, okunabilir bir detail, instance yolu ve destekle iletişime geçerken belirtmeniz gereken bir request_id:

error body
{
  "title": "Forbidden",
  "status": 403,
  "detail": "key lacks scope 'history'",
  "instance": "/v1/candles/bist:THYAO",
  "request_id": "0f3c9a1e-7b42-4d0a-9c11-8e2f5a6b3d40"
}
AlanTürNotlar
titlestringDurum sınıfı için kısa, kararlı etiket (üzerinde switch yapmak güvenli)
statusintHTTP durum kodunu yansıtır
detailstringOkunabilir ayrıntılar (ör. hangi kapsamın eksik olduğu, hangi kimliğin geçersiz olduğu)
instancestringHatayı üreten istek yolu
request_idstringİstek başına benzersizdir — destekle paylaşın; ayrıca her yanıtta X-Request-Id başlığı olarak döner

Kullanılan durum kodları

AlanTürNotlar
401UnauthorizedEksik veya geçersiz X-API-Key. Başlık adını ve anahtarın aktif olduğunu (yenilenmemiş/iptal edilmemiş) kontrol edin.
403ForbiddenAnahtar geçerli ama gereken kapsamdan yoksun — eksik kapsam detail içinde belirtilir. Anahtara ekleyin (veya izin veren bir plan talep edin).
404Not FoundBöyle bir rota veya kaynak yok (ör. bir profil rotasında bilinmeyen bir fon kodu).
422UnprocessableDoğrulama hatası — bozuk bir enstrüman kimliği, desteklenmeyen bir ?currency= hedefi, hatalı bir tarih aralığı veya çözünürlük. detail neyi düzelteceğinizi söyler.
429Too Many RequestsHız limiti aşıldı. X-RateLimit-* başlıkları + Retry-After ile geri çekilin (aşağıya bakın).
503Service UnavailableÜst kaynak verisi anlık olarak kullanılamıyor — bir dönüşüm için eksik bir FX kuru ya da soğuk bir önbellek. Geri çekilmeyle yeniden denemek güvenlidir; hiçbir zaman bir değer uydurmaz veya eski bir değeri iliştirmeyiz.
Bir 404 (bilinmeyen enstrüman kimliği) ile bir 422 (bozuk kimlik) arasındaki ayrım kasıtlıdır: bist:NOPE (biçimi doğru, listelenmemiş) bir 404'tür; THYAO ise piyasa ön eki gerektiren bir rotada ön ek olmadan bir 422'dir.

Hız limitleri (429)

Limitler, anahtar başına bir token kovasıdır: ani yük payı olan sürekli bir hız (test planı: sürekli 10 istek/sn, ani yük 20). Her yanıt — başarılı ya da hatalı — mevcut bütçeyi taşır:

response headers (on every request)
X-RateLimit-Limit: 20
X-RateLimit-Remaining: 14
X-Request-Id: 0f3c9a1e-7b42-4d0a-9c11-8e2f5a6b3d40

Aştığınızda, bir 429 başlığı (saniye) ve Retry-After ile birlikte bir X-RateLimit-Remaining: 0 alırsınız:

429 body
{
  "title": "Too Many Requests",
  "status": 429,
  "detail": "rate limit exceeded, retry after 1s",
  "instance": "/v1/quotes/bist:THYAO",
  "request_id": "…"
}

Yeniden deneme rehberi

  • 429 ve 503 geçicidir — üstel geri çekilmeyle yeniden deneyin (~1sn başlayın, birkaç denemeyle sınırlayın). 429 için varsa Retry-After değerine uyun; aksi halde kova dolana kadar bekleyin.
  • 429 dışındaki 4xx (401/403/404/422) bizim değil sizin hatanızdır — körlemesine yeniden denemeyin; önce anahtarı, kapsamı, kimliği veya parametreleri düzeltin.
  • Sıkı sorgulama yerine WebSocket tercih edin — REST hız bütçesini tüketmez ve her yenileme döngüsünde veri iter.
  • Hatalardan gelen request_id değerini her zaman kaydedin. destekle iletişime geçtiğinizde bunu ekleyin — tam isteği günlüklerimizde bulmamızı sağlar.