Kredit dan batas

AstroWay menggunakan model kredit alih-alih penghitung permintaan sederhana.

Dapatkan kunci API dalam 60 detik

aw_test_demo_aaaa1111

Daftar - gratis→

Ini lebih adil: endpoint ringan (/planets) berharga 10 kredit, sedangkan yang berat (/rectification) berharga 500.

Dua Jenis Batas

1. Anggaran Kredit Harian/Bulanan

Jumlah kredit per bulan tergantung pada paket:

Paket	Kredit/Bulan	Batas Harian
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

Segera setelah kredit habis, permintaan berikutnya akan mengembalikan 402 Payment Required (Free) atau memicu penagihan overage (Indie+).

2. Rate Limit (permintaan per menit)

Paket	RPM
Free	10 req/min
Indie	30 req/min
Starter	120 req/min
Pro	400 req/min
Business	1.000 req/min
Enterprise	Custom

Rate limit adalah sliding window. Jika kamu melakukan 120 permintaan dalam 10 detik, 50 detik berikutnya pada kunci tersebut akan menghasilkan 429.

Tips

Rate limit dan anggaran kredit bersifat independen. Kamu bisa memiliki kredit tetapi tidak melewati rate limit. Dan sebaliknya.

Jika sebuah kunci memiliki daftar asal yang diizinkan, setiap entri daftar menerima bagiannya sendiri dari batas ini: batas kunci dibagi dengan jumlah entri, dibulatkan ke atas. Satu situs dengan widget tersemat tidak dapat menghabiskan kuota yang dibayar oleh pemilik kunci, sementara domainnya yang lain tetap berfungsi. Batas total kunci tidak bertambah: bagian-bagian membaginya, bukan menambahkannya.

Penghitung dilakukan berdasarkan entri, bukan berdasarkan host yang datang. Entri *.example.com adalah satu penghitung untuk semua subdomain, jika tidak, pembatasan akan dihindari dengan membuat subdomain baru untuk setiap permintaan. Ketika ada satu entri dalam daftar, bagiannya sama dengan batas dan tidak ada yang berubah.

3. Endpoint Publik (tanpa kunci)

14 kamus referensi /v1/reference/* (signs, planets, houses, aspects, elements, modalities, polarities, dignities, decans, nakshatras, lots, asteroids, zodiac-systems, glyphs) dilayani secara publik, tanpa X-Api-Key dan berharga 0 kredit. Batasnya adalah 30 permintaan / jam dari satu IP. Data yang sama ini juga diekspos sebagai MCP Resources astroway://reference/<slug> untuk agen LLM.

Batas yang sama berlaku untuk namespace publik lainnya: /v1/public/*, /v1/embed/*, /v1/i18n/*.

Kuota untuk Render di Sisi Server

30 permintaan per jam dirancang untuk browser: setiap pengunjung membawa IP-nya sendiri dan kuotanya sendiri. Namun, jika permintaan dilakukan oleh server kamu (plugin WordPress, SSR, cache-warming), satu alamat melayani semua pengunjung dan menghabiskan batas dalam beberapa kali muat ulang halaman.

Untuk kasus ini, kirimkan header X-AstroWay-Site-URL dengan alamat situs:

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

Mode	Batas
Tanpa header	30 permintaan / jam per IP; widget /v1/embed/* memiliki 120 / jam per IP terpisah
Dengan header	300 permintaan / jam per situs, batas atas 600 / jam per IP

Header diizinkan di CORS dan bukan kredensial, sehingga batas atas IP tetap ada: berapa pun domain yang kamu sebutkan dari satu alamat, totalnya tidak akan lebih dari 600 permintaan per jam dari sana. Kedua penghitung diperlukan secara bersamaan: penghitung situs aktif ketika satu situs berasal dari banyak alamat (CDN, load balancer), penghitung IP aktif ketika banyak nama berasal dari satu alamat.

Satu panggilan tidak selalu satu unit. Endpoint publik yang berat menghabiskan lebih banyak dari keranjang yang sama, dan tidak mendapatkan keranjang terpisah. POST /v1/public/synastry berharga 3, karena ini adalah dua chart dan matriks aspek 45 sel: batas atas praktis untuk ini adalah 10 per jam dari alamat yang tidak disebutkan, 100 untuk situs yang disebutkan, dan 200 per alamat. Semua yang lain berharga 1. Ketika panggilan berharga lebih dari satu unit, respons akan menyatakannya di header X-RateLimit-Cost, dan panggilan yang berharga lebih dari yang tersisa di keranjang akan ditolak, bukan menjadi minus.

Penghitung mana yang paling ketat saat ini, akan disebutkan di header respons X-RateLimit-Scope (ip atau site). Header X-RateLimit-* lainnya hanya menggambarkan penghitung tersebut, yaitu hanya satu dari dua penghitung. Yang kedua terlihat di X-RateLimit-Counters:

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

Formatnya adalah scope=sisa/batas dipisahkan koma. Header hanya muncul ketika memang ada dua penghitung: panggilan anonim dengan X-AstroWay-Site-URL. Panggilan dengan kunci berbayar dihitung berdasarkan kunci kamu dan tarif kamu, di sana hanya ada satu penghitung dan tidak ada header. Bacalah ini jika kamu merender beberapa domain dari satu alamat di sisi server: keranjang situs untuk setiap domain berbeda, tetapi batas atas IP bersifat bersama, dan itulah yang akan tercapai terlebih dahulu.

Cache respons di sisi kamu: horoskop harian tidak berubah sepanjang hari, dan cache hingga tengah malam sepenuhnya menghilangkan masalah batas.

Kunci Berbayar pada Endpoint Publik. /v1/public/* dan /v1/embed/* berfungsi tanpa kunci, tetapi jika kamu mengirimkannya (X-Api-Key), permintaan dihitung berdasarkan tarif kamu, bukan kuota anonim, dan tidak ada tanda air gratis di respons. Ini masuk akal untuk render di sisi server: satu mesin melayani semua pengunjung, dan 300/jam anonim tidak cukup untuknya.

Tabel Biaya

Tabel transparan lengkap dengan semua 771+ endpoint dan biayanya ada di halaman Biaya Endpoint. DivineAPI/AstrologyAPI/Prokerala tidak mempublikasikan tabel semacam itu. Panduan singkat:

Tier	Kredit	Waktu Khas	Contoh
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	beberapa detik	/rectification/trutine
6	500	hingga 120 detik	/rectification

Header Respons

Setiap respons berisi:

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: berapa banyak yang didebit untuk permintaan ini
• X-Credits-Remaining: sisa anggaran bulanan
• X-Credits-Limit: anggaran kredit penuh per bulan (sesuai paket)
• X-Credits-Reset: tanggal pembaruan saldo ISO-8601
• X-RateLimit-*: status sliding window saat ini (format standar)
  • X-RateLimit-Scope: penghitung mana yang paling ketat saat ini: ip, site, atau key. Nilai key berarti permintaan dihitung berdasarkan kunci kamu dan batas tarif kamu, bukan kuota anonim.
  • X-RateLimit-Counters: pada endpoint publik, yang dipanggil dengan X-AstroWay-Site-URL, semua penghitung yang digunakan untuk menghitung permintaan, dalam format scope=sisa/batas. Header di atas hanya menggambarkan yang paling ketat.
  • X-RateLimit-Reset: momen ketika permintaan tertua akan keluar dari jendela, yaitu ketika satu slot akan kosong. Ini bukan waktu pembukaan penuh bucket: setelah itu satu permintaan akan lewat, dan Reset akan bergeser ke waktu berikutnya. Klien yang menunggu hingga Reset dan kemudian mengirimkan banyak permintaan akan kembali menerima 429, jadi lebih aman untuk mengirim satu permintaan pada satu waktu atau menyimpan respons di sisi kamu.
  • Permintaan yang ditolak (429) tidak menghabiskan kuota dan tidak menggeser jendela: penghitung hanya diisi ulang oleh permintaan yang berhasil.
  • X-RateLimit-Origin-Limit dan X-RateLimit-Origin-Remaining: hanya muncul ketika permintaan telah melewati entri dari daftar asal yang diizinkan, dan menunjukkan bagian yang dialokasikan khusus untuk entri tersebut. Penolakan karena bagian ini juga 429, dan teksnya menyebutkan entri mana yang telah habis.
• X-Subscription-Status dan X-Subscription-Grace-Ends: hanya muncul ketika periode berbayar telah berakhir, dan periode tenggang 3 hari masih berlangsung (X-Subscription-Status: grace). Permintaan dilayani berdasarkan tarif kamu hingga waktu di X-Subscription-Grace-Ends, setelah itu responsnya adalah 402 SUBSCRIPTION_EXPIRED. Jika klien kamu mencatat header, ini adalah sinyal paling awal bahwa sudah saatnya untuk memperpanjang paket.
• X-Request-Id: ID permintaan, 32 karakter heksadesimal; sebutkan ini saat menghubungi dukungan

Berapa Banyak yang Sudah Terpakai: Tiga Cara

Kamu dapat memeriksa saldo kredit saat ini dengan tiga cara - dari yang tercepat hingga yang paling detail:

1. Di setiap respons: header X-Credits-Remaining / X-Credits-Used / X-Credits-Limit dikembalikan pada setiap permintaan (bahkan pada kesalahan). Tidak perlu memanggil apa pun tambahan - saldo selalu terlihat.
2. Dengan permintaan terpisah: GET /v1/keys/usage dengan X-Api-Key kamu mengembalikan credits (used / remaining / limit / reset), usage (permintaan per hari ini / minggu / bulan), dan 20 endpoint teratas selama 30 hari. Satu panggilan, tanpa kunci admin terpisah.
3. Di dashboard: api.astroway.info/dashboard/billing menunjukkan saldo, grafik penggunaan, dan rincian berdasarkan endpoint secara real-time.

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

Tips

Tidak seperti kebanyakan API (Anthropic, OpenAI), AstroWay mengembalikan sisa saldo langsung di header setiap respons (X-Credits-Remaining) - kamu tidak perlu pergi ke dashboard atau API penggunaan terpisah untuk mengetahui berapa banyak yang tersisa.

Caching

Permintaan identik dalam waktu 5 menit dikembalikan dari cache tanpa pengurangan kredit. Ini adalah header terpisah:

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

Apa yang dianggap “identik”:

• Endpoint yang sama
• JSON body yang sama (byte-per-byte setelah normalisasi spasi)
• Kunci API yang sama

Ini aman, karena semua endpoint bersifat deterministik - input yang sama selalu menghasilkan output yang sama.

Streaming dan Webhook

Streaming (/stream/*)

10 endpoint stream dikenakan biaya sebagai Tier 1: 10 kredit per panggilan. Setiap panggilan menghitung ulang posisi planet, jadi ini adalah perhitungan penuh, bukan pencarian yang di-cache - tidak ada tarif “lebih murah” terpisah per tick.

Setiap respons berisi dua bidang untuk polling yang hemat:

• tickSeconds: interval polling yang direkomendasikan;
• nextEventAt: kapan status akan berubah berikutnya.

Polling lebih sering dari tickSeconds - hanya membuang-buang kredit: status tidak akan berubah hingga nextEventAt.

Perhatian

Contoh anggaran: satu stream, di-polling setiap 60 detik = 1.440 panggilan/hari × 10 kredit = 14.400 kredit/hari. Pada Indie (50.000/bulan) ini sekitar 3,5 hari satu stream. Untuk streaming berkelanjutan - Starter+.

Webhook (/webhooks/*)

Operasi CRUD manajemen langganan (/webhooks/subscribe, daftar, lihat, hapus, /test) berharga Tier 1: 10 kredit masing-masing. Ini adalah panggilan yang jarang.

Pengiriman event (server → URL kamu) tidak dikenakan biaya: kredit hanya didebit untuk panggilan CRUD manajemen. Mendukung 12 jenis event (report-ready, transit-alert, eclipse-alert, dasha-change, sign-ingress, dll.).

Webhook tersedia mulai dari paket Pro ke atas.

Apa yang Harus Dilakukan Saat Melebihi Batas

402 Payment Required: Kredit Habis

{
  "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"
  }
}

Opsi:

• Upgrade Paket: langsung mendapatkan anggaran baru
• Overage (Starter/Pro): aktif secara otomatis, jika tidak dinonaktifkan di pengaturan
• Menunggu Reset (Free): tanggal 1 bulan berikutnya

429 Too Many Requests: RPM Terlampaui

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

Header Retry-After: 12 adalah header HTTP standar, klien HTTP kamu harus memahaminya.

Penanganan yang Benar:

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();
}

Perhatian

Jangan lakukan exponential backoff tanpa cap - Retry-After di respons sudah berisi angka yang tepat. Percayalah padanya.

Estimasi Anggaran di Muka

Sebelum integrasi, perkirakan berapa banyak kredit yang kamu butuhkan per bulan:

monthly_credits = daily_active_users × calls_per_user × avg_cost_per_call × 30

Contoh: aplikasi dengan 500 DAU, setiap pengguna melakukan 3 perhitungan chart + 1 sinastri per hari:

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

Kalkulator anggaran ada di halaman Tarif.

Selanjutnya

• Error: referensi lengkap kode error
• Idempotency: cara melakukan permintaan berulang dengan aman