Krediler ve limitler

AstroWay, basit bir istek sayacı yerine kredi modeli kullanır.

60 saniyede API anahtarı al

aw_test_demo_aaaa1111

Ücretsiz kaydol→

Bu daha adildir: hafif endpoint’ler (/planets) 10 kredi, ağır olanlar (/rectification) ise 500 kredi maliyetindedir.

İki Tür Limit

1. Günlük/Aylık Kredi Bütçesi

Aylık kredi miktarı plana göre değişir:

Plan	Kredi/Ay	Günlük Limit
Free	10 000	~333
Indie	50 000	~1 667
Starter	200 000	~6 667
Pro	800 000	~26 667
Business	3 500 000	~116 666
Enterprise	Custom	Custom

Krediler bittiğinde, sonraki istekler 402 Payment Required (Free) döndürür veya aşım faturalandırmasını (Indie+) başlatır.

2. Hız Limiti (dakika başına istek)

Plan	İstek/Dakika
Free	10 istek/dakika
Indie	30 istek/dakika
Starter	120 istek/dakika
Pro	400 istek/dakika
Business	1 000 istek/dakika
Enterprise	Custom

Hız limiti kayan pencere prensibine göre çalışır. Eğer 10 saniyede 120 istek gönderdiysen, bu anahtar üzerinde sonraki 50 saniye boyunca 429 yanıtı alırsın.

İpucu

Hız limiti ve kredi bütçesi bağımsızdır. Kredilerin olabilir ama hız limitini geçemeyebilirsin. Ve tersi.

Eğer bir anahtarın izin verilen kaynaklar listesi varsa, listenin her kaydı bu limitin kendi payını alır: anahtarın limiti, kayıt sayısına bölünür ve yukarı yuvarlanır. Gömülü bir widget’a sahip tek bir site bu yüzden anahtar sahibinin ödediği kotayı tüketemez ve diğer alan adları çalışmaya devam eder. Anahtarın genel limiti artmaz: paylar onu böler, ona eklenmez.

Sayaç, gelen ana bilgisayara göre değil, kayda göre tutulur. *.example.com kaydı tüm alt alan adları için tek bir sayaçtır, aksi takdirde, her istek için yeni bir alt alan adı uydurularak kısıtlama aşılırdı. Listede tek bir kayıt olduğunda, pay limite eşittir ve hiçbir şey değişmez.

3. Herkese Açık Endpoint’ler (Anahtarsız)

14 referans sözlüğü /v1/reference/* (signs, planets, houses, aspects, elements, modalities, polarities, dignities, decans, nakshatras, lots, asteroids, zodiac-systems, glyphs) Herkese açık olarak, X-Api-Key olmadan sunulur ve 0 kredi maliyeti vardır. Kısıtlama - tek bir IP’den saatte 30 istek. Aynı veriler, LLM ajanları için MCP Kaynakları astroway://reference/<slug> olarak da sunulmaktadır.

Aynı limit, diğer herkese açık ad alanları için de geçerlidir: /v1/public/*, /v1/embed/*, /v1/i18n/*.

Sunucu Tarafı Render Kotası

Saatte 30 istek tarayıcı için hesaplanmıştır: her ziyaretçi kendi IP’sini ve kendi kotasını getirir. Ancak istekleri sunucun (WordPress eklentisi, SSR, önbellek ısıtma) yapıyorsa, tek bir adres tüm ziyaretçiler adına hareket eder ve birkaç sayfa yenilemesinde limiti tüketir.

Bu durum için, site adresiyle birlikte X-AstroWay-Site-URL başlığını gönder:

X-AstroWay-Site-URL: https://example.com/

Mod	Limit
Başlıksız	IP başına saatte 30 istek; /v1/embed/* widget’ları IP başına ayrı 120 / saat limitine sahiptir
Başlıklı	Site başına saatte 300 istek, IP başına saatte 600 üst limit

Başlık CORS’ta izinlidir ve kimlik bilgisi değildir, bu yüzden IP üst limiti kalır: tek bir adresten kaç alan adı belirtilirse belirtilsin, toplamda saatte 600’den fazla istek gitmez. Her iki sayaç da aynı anda gereklidir: site sayacı, tek bir site birçok adresten (CDN, yük dengeleyici) geldiğinde devreye girer; IP sayacı, tek bir adresten birçok isim geldiğinde devreye girer.

Tek bir çağrı her zaman tek bir birim değildir. Ağır bir herkese açık endpoint, aynı sepetten daha fazlasını harcar, ayrı bir sepet almaz. POST /v1/public/synastry 3 maliyetindedir, çünkü bu iki harita ve 45 hücreli bir açı matrisidir: bunun için pratik üst limit, beyan edilmemiş bir adresten saatte 10, beyan edilmiş bir site için 100 ve adres başına 200’dür. Diğer her şey 1 maliyetindedir. Bir çağrının maliyeti birden fazla olduğunda, yanıt bunu X-RateLimit-Cost başlığında belirtir ve sepette kalandan daha fazla maliyeti olan bir çağrı reddedilir, eksiye düşmez.

Şu anda hangi sayacın en sıkı olduğunu yanıt başlığı X-RateLimit-Scope (ip veya site) belirtir. Diğer X-RateLimit-* başlıkları sadece onu, yani iki sayaçtan sadece birini açıklar. İkincisi X-RateLimit-Counters içinde görülebilir:

X-RateLimit-Scope: site
X-RateLimit-Limit: 300
X-RateLimit-Remaining: 297
X-RateLimit-Counters: ip=597/600, site=297/300

Format - scope=kalan/limit virgülle ayrılmış. Başlık yalnızca gerçekten iki sayaç olduğunda gelir: X-AstroWay-Site-URL ile yapılan anonim bir çağrı. Ücretli bir anahtarla yapılan çağrı, anahtarın ve tarifesinin limitine göre sayılır, orada tek bir sayaç vardır ve başlık yoktur. Eğer sunucudan tek bir adresten birden fazla alan adı render ediyorsan bunu oku: her alan adının site sepeti kendine aitken, IP üst limiti ortaktır ve ilk olarak o sınıra takılır.

Yanıtları kendi tarafında önbelleğe al: günlük burç yorumu gün boyunca değişmez ve gece yarısına kadar önbellek, limit sorununu tamamen ortadan kaldırır.

Herkese Açık Endpoint’lerde Ücretli Anahtar. /v1/public/* ve /v1/embed/* anahtarsız çalışır, ancak eğer onu (X-Api-Key) iletirsen, istek anonim kota yerine tarifene göre sayılır ve yanıtta ücretsiz filigran olmaz. Bu, sunucu tarafı render için mantıklıdır: tek bir makine tüm ziyaretçiler adına hareket eder ve anonim 300/saat ona yetmez.

Maliyet Tablosu

Tüm 771+ endpoint’leri ve maliyetlerini içeren tam şeffaf tablo Endpoint Maliyetleri sayfasındadır. DivineAPI/AstrologyAPI/Prokerala böyle bir tablo yayınlamaz. Kısa bir referans:

Katman	Kredi	Tipik Süre	Örnekler
1	10	< 50 ms	/planets, /moon-voc, /iching
2	20	50–200 ms	/chart, /harmonics, /horary
3	50	200–500 ms	/synastry, /progressions, /acg
4	100	> 500 ms	/transit-calendar, /forecast-calendar
5	250	birkaç s	/rectification/trutine
6	500	120 saniyeye kadar	/rectification

Yanıt Başlıkları

Her yanıt şunları içerir:

X-Credits-Used: 20
X-Credits-Remaining: 9980
X-Credits-Limit: 10000
X-Credits-Reset: 2026-05-01T00:00:00Z
X-RateLimit-Limit: 120
X-RateLimit-Remaining: 118
X-RateLimit-Reset: 1714521600
X-RateLimit-Origin-Limit: 60
X-RateLimit-Origin-Remaining: 59
X-Request-Id: 8aec43e9bc749b37e998a489bbad1757

• X-Credits-Used: bu istek için ne kadar düşüldü
• X-Credits-Remaining: aylık bütçede kalan
• X-Credits-Limit: aylık tam kredi bütçesi (plana göre)
• X-Credits-Reset: bakiyenin yenilenme ISO-8601 tarihi
• X-RateLimit-*: kayan pencerenin mevcut durumu (standart format)
  • X-RateLimit-Scope: şu anda hangi sayacın en sıkı olduğu: ip, site veya key. key değeri, isteğin anonim kota yerine anahtarın ve tarifesinin limitine göre sayıldığı anlamına gelir.
  • X-RateLimit-Counters: X-AstroWay-Site-URL ile çağrılan herkese açık bir endpoint’te, isteğin sayıldığı tüm sayaçlar scope=kalan/limit formatında. Yukarıdaki başlıklar sadece en sıkı olanı açıklar.
  • X-RateLimit-Reset: pencereden en eski isteğin düşeceği an, yani bir slotun boşalacağı zaman. Bu, sepetin tamamen açılma zamanı değildir: ondan sonra bir istek geçer ve Reset zaman olarak bir sonrakine kayar. Reset’e kadar bekleyip sonra bir paket gönderen bir istemci tekrar 429 alacaktır, bu yüzden tek tek istek göndermek veya yanıtları kendi tarafında önbelleğe almak daha güvenlidir.
  • Reddedilen bir istek (429) kota harcamaz ve pencereyi kaydırmaz: sayaç yalnızca başarılı isteklerle dolar.
  • X-RateLimit-Origin-Limit ve X-RateLimit-Origin-Remaining: yalnızca istek, izin verilen kaynaklar listesindeki bir kayda göre geçtiğinde gelir ve bu kayda ayrılan payı gösterir. Bu pay için reddedilme de 429’dur ve metinde hangi kaydın tükendiği belirtilir.
• X-Subscription-Status ve X-Subscription-Grace-Ends: yalnızca ödeme dönemi sona erdiğinde ve 3 günlük ek süre (X-Subscription-Status: grace) hala devam ettiğinde gelir. İstekler, X-Subscription-Grace-Ends’deki zamana kadar tarifene göre işlenir, ondan sonra yanıt 402 SUBSCRIPTION_EXPIRED olur. Eğer istemcin başlıkları logluyorsa, bu, planı yenileme zamanının geldiğine dair en erken sinyaldir.
• X-Request-Id: isteğin tanımlayıcısı, 32 onaltılık karakter; destekle iletişime geçerken bunu belirt.

Ne Kadar Harcandı: Üç Yöntem

Mevcut kredi bakiyeni üç yolla kontrol edebilirsin - en hızlıdan en detaylıya:

1. Her Yanıtta: X-Credits-Remaining / X-Credits-Used / X-Credits-Limit başlıkları herhangi bir isteğe (hatta hataya bile) döndürülür. Ekstra bir şey çağırmana gerek yok - bakiye her zaman gözünün önünde.
2. Ayrı Bir İstekle: GET /v1/keys/usage kendi X-Api-Key’inle credits (kullanılan / kalan / limit / sıfırlama), usage (bugün / hafta / ay için istekler) ve son 30 günün en iyi 20 endpoint’ini döndürür. Tek bir çağrı, ayrı bir yönetici anahtarı olmadan.
3. Kontrol Panelinde: api.astroway.info/dashboard/billing bakiyeyi, kullanım grafiğini ve endpoint’lere göre gerçek zamanlı dökümü gösterir.

curl https://api.astroway.info/v1/keys/usage \
  -H "X-Api-Key: $AW_KEY"

İpucu

Çoğu API’nin (Anthropic, OpenAI) aksine, AstroWay kalan bakiyeyi doğrudan her yanıtın başlığında (X-Credits-Remaining) döndürür - ne kadar kaldığını öğrenmek için kontrol paneline veya ayrı bir kullanım API’sine gitmene gerek yok.

Önbelleğe Alma

5 dakika içinde yapılan aynı istekler, kredi düşülmeden önbellekten döndürülür. Bu ayrı bir başlıktır:

X-Cache: HIT
X-Credits-Used: 0

Ne “aynı” kabul edilir:

• Aynı endpoint
• Aynı JSON gövdesi (boşluk normalleştirmesinden sonra bayt bayt)
• Aynı API anahtarı

Bu güvenlidir, çünkü tüm endpoint’ler deterministiktir - aynı girdi her zaman aynı çıktıyı verir.

Akış ve Webhook’lar

Akış (/stream/*)

10 akış endpoint’i Katman 1: çağrı başına 10 kredi olarak ücretlendirilir. Her çağrı gezegen konumlarını yeniden hesaplar, bu yüzden bu tam teşekküllü bir hesaplamadır, önbelleğe alınmış bir arama değil - tik başına ayrı bir “daha ucuz” oran yoktur.

Her yanıt, ekonomik sorgulama için iki alan içerir:

• tickSeconds: önerilen sorgulama aralığı;
• nextEventAt: durumun bir sonraki değişeceği zaman.

tickSeconds’tan daha sık sorgulama yapmak - kredileri boşuna yakmaktır: durum nextEventAt’e kadar değişmeyecektir.

Dikkat

Bütçe örneği: her 60 saniyede bir sorgulanan bir akış = günde 1.440 çağrı × 10 kredi = günde 14.400 kredi. Indie (aylık 50.000) planında bu, tek bir akış için ~3.5 gün demektir. Sürekli akış için - Starter+.

Webhook’lar (/webhooks/*)

Abonelik yönetimi CRUD işlemleri (/webhooks/subscribe, listeleme, görüntüleme, silme, /test) her biri Katman 1: 10 kredi maliyetindedir. Bunlar nadir çağrılardır.

Olay teslimatı (sunucu → URL’n) ücretlendirilmez: krediler yalnızca yönetim CRUD çağrıları için düşülür. 12 olay türü desteklenir (report-ready, transit-alert, eclipse-alert, dasha-change, sign-ingress vb.).

Webhook’lar Pro ve üzeri planlarda mevcuttur.

Limitler Aşıldığında Ne Yapmalı

402 Payment Required: Krediler Bitti

{
  "error": {
    "code": "credits_exhausted",
    "message": "Monthly credit budget exhausted. Upgrade plan or wait for reset.",
    "credits_remaining": 0,
    "credits_reset": "2026-05-01T00:00:00Z",
    "upgrade_url": "https://api.astroway.info/dashboard/billing"
  }
}

Seçenekler:

• Plan Yükseltme: hemen yeni bir bütçe alırsın
• Aşım (Starter/Pro): ayarlarda kapatılmadıysa otomatik olarak etkinleşir
• Sıfırlamayı Bekle (Free): sonraki ayın 1’i

429 Too Many Requests: RPM Aşıldı

{
  "error": {
    "code": "rate_limit_exceeded",
    "message": "Too many requests. Retry after 12 seconds.",
    "retry_after_seconds": 12
  }
}

Retry-After: 12 başlığı - standart bir HTTP başlığıdır, HTTP istemcin bunu anlamalıdır.

Doğru İşleme:

async function callWithRetry(endpoint: string, body: object) {
  const response = await fetch(endpoint, {
    method: 'POST',
    headers: { 'X-Api-Key': key, 'Content-Type': 'application/json' },
    body: JSON.stringify(body),
  });

  if (response.status === 429) {
    const retryAfter = Number(response.headers.get('Retry-After') ?? 1);
    await new Promise((r) => setTimeout(r, retryAfter * 1000));
    return callWithRetry(endpoint, body);
  }

  return response.json();
}

Dikkat

Üst limitsiz üstel geri çekilme yapma - yanıttaki Retry-After zaten kesin sayıyı içeriyor. Ona güven.

Bütçeyi Önceden Tahmin Etme

Entegrasyondan önce, aylık ne kadar krediye ihtiyacın olduğunu tahmin et:

monthly_credits = daily_active_users × calls_per_user × avg_cost_per_call × 30

Örnek: 500 DAU’lu bir uygulama, her kullanıcı günde 3 harita hesaplaması + 1 sinastri yapar:

500 × (3 × 20 + 1 × 50) × 30 = 500 × 110 × 30 = 1,650,000 credits/mo
→ Enterprise (custom)

Bütçe hesaplayıcı - Fiyatlandırma sayfasında.

Sonraki

• Hatalar: hata kodlarının tam referansı
• Idempotency: tekrarlayan istekleri güvenli bir şekilde nasıl yaparsın