Credits και όρια

Το AstroWay χρησιμοποιεί ένα μοντέλο πιστώσεων αντί για έναν απλό μετρητή αιτημάτων.

Είναι πιο δίκαιο: τα ελαφριά endpoints (/planets) κοστίζουν 10 πιστώσεις, τα βαριά (/rectification) - 500.

Δύο είδη ορίων

1. Ημερήσιος/μηνιαίος προϋπολογισμός πιστώσεων

Ο αριθμός των πιστώσεων ανά μήνα εξαρτάται από το πλάνο:

Πλάνο	Πιστώσεις/μήνα	Ημερήσιο όριο
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

Μόλις εξαντληθούν οι πιστώσεις - τα επόμενα αιτήματα επιστρέφουν 402 Payment Required (Free) ή ενεργοποιούν την τιμολόγηση overage (Indie+).

2. Όριο ρυθμού (αιτήματα ανά λεπτό)

Πλάνο	RPM
Free	10 req/min
Indie	30 req/min
Starter	120 req/min
Pro	400 req/min
Business	1 000 req/min
Enterprise	Custom

Το όριο ρυθμού είναι ένα κινούμενο παράθυρο (sliding window). Αν έκανες 120 αιτήματα σε 10 δευτερόλεπτα, τα επόμενα 50 δευτερόλεπτα σε αυτό το κλειδί - 429.

Αν ένα κλειδί έχει μια λίστα επιτρεπόμενων προελεύσεων, κάθε καταχώριση της λίστας λαμβάνει το δικό της μερίδιο αυτού του ορίου: το όριο του κλειδιού διαιρείται με τον αριθμό των καταχωρίσεων, στρογγυλοποιημένο προς τα πάνω. Ένας ιστότοπος με ενσωματωμένο widget δεν μπορεί λόγω αυτού να καταναλώσει την ποσόστωση που πληρώνει ο κάτοχος του κλειδιού, ενώ οι άλλοι τομείς του παραμένουν λειτουργικοί. Το συνολικό όριο του κλειδιού δεν αυξάνεται: τα μερίδια το διαιρούν, δεν προστίθενται σε αυτό.

Ο μετρητής τηρείται ακριβώς ανά καταχώριση, και όχι ανά host που έρχεται. Η καταχώριση *.example.com είναι ένας μετρητής για όλους τους υποτομείς, αλλιώς ο περιορισμός θα παρακαμφθεί με την επινόηση ενός νέου υποτομέα για κάθε αίτημα. Όταν υπάρχει μία καταχώριση στη λίστα, το μερίδιο είναι ίσο με το όριο και τίποτα δεν αλλάζει.

3. Δημόσια endpoints (χωρίς κλειδί)

14 λεξικά αναφοράς /v1/reference/* (signs, planets, houses, aspects, elements, modalities, polarities, dignities, decans, nakshatras, lots, asteroids, zodiac-systems, glyphs) εξυπηρετούνται δημόσια, χωρίς X-Api-Key και κοστίζουν 0 πιστώσεις. Περιορισμός - 30 αιτήματα / ώρα από μία IP. Αυτά τα δεδομένα εκτίθενται επίσης ως MCP Resources astroway://reference/<slug> για LLM-agents.

Το ίδιο όριο ισχύει για τα υπόλοιπα δημόσια namespaces: /v1/public/*, /v1/embed/*, /v1/i18n/*.

Ποσόστωση για rendering στον server

Τα 30 αιτήματα ανά ώρα υπολογίζονται για τον browser: κάθε επισκέπτης φέρνει τη δική του IP και τη δική του ποσόστωση. Αν όμως τα αιτήματα γίνονται από τον server σου (WordPress-plugin, SSR, cache-warming), μία διεύθυνση εξυπηρετεί όλους τους επισκέπτες και εξαντλεί το όριο μερικές φορές ανανεώνοντας τη σελίδα.

Για αυτή την περίπτωση, στείλε το header X-AstroWay-Site-URL με τη διεύθυνση του ιστότοπου:

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

Λειτουργία	Όριο
Χωρίς header	30 αιτήματα / ώρα ανά IP· τα widgets `/v1/embed/*` έχουν ξεχωριστά 120 / ώρα ανά IP
Με header	300 αιτήματα / ώρα ανά ιστότοπο, ανώτατο όριο 600 / ώρα ανά IP

Το header επιτρέπεται στο CORS και δεν είναι διαπιστευτήρια, οπότε το ανώτατο όριο ανά IP παραμένει: όσα domains κι αν δηλωθούν από μία διεύθυνση, συνολικά από εκεί δεν θα γίνουν περισσότερα από 600 αιτήματα ανά ώρα. Και οι δύο μετρητές χρειάζονται ταυτόχρονα: ο μετρητής του ιστότοπου ενεργοποιείται όταν ένας ιστότοπος κάνει αιτήματα από πολλές διευθύνσεις (CDN, load balancer), ο μετρητής IP ενεργοποιείται όταν από μία διεύθυνση έρχονται πολλά ονόματα.

Μία κλήση δεν είναι πάντα μία μονάδα. Ένα βαρύ δημόσιο endpoint καταναλώνει περισσότερο από το ίδιο καλάθι, και δεν λαμβάνει ξεχωριστό. Το POST /v1/public/synastry κοστίζει 3, γιατί είναι δύο χάρτες και ένας πίνακας όψεων 45 κελιών: το πρακτικό ανώτατο όριο για αυτό είναι 10 ανά ώρα από μη δηλωμένη διεύθυνση, 100 για δηλωμένο ιστότοπο και 200 ανά διεύθυνση. Όλα τα άλλα κοστίζουν 1. Όταν μια κλήση κοστίζει περισσότερο από μία μονάδα, η απάντηση το αναφέρει στο header X-RateLimit-Cost, και μια κλήση που κοστίζει περισσότερο από ό,τι έχει απομείνει στο καλάθι, απορρίπτεται, και δεν πηγαίνει σε αρνητικό.

Ποιος μετρητής είναι ο πιο περιοριστικός αυτή τη στιγμή, το λέει το header της απάντησης X-RateLimit-Scope (ip ή site). Τα υπόλοιπα headers X-RateLimit-* περιγράφουν μόνο αυτόν, δηλαδή μόνο έναν από τους δύο μετρητές. Ο δεύτερος φαίνεται στο X-RateLimit-Counters:

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

Μορφή - scope=υπόλοιπο/όριο χωρισμένο με κόμμα. Το header έρχεται μόνο όταν υπάρχουν πράγματι δύο μετρητές: μια ανώνυμη κλήση με X-AstroWay-Site-URL. Μια κλήση με πληρωμένο κλειδί υπολογίζεται με βάση το κλειδί σου και το τιμολόγιό σου, εκεί υπάρχει ένας μετρητής και δεν υπάρχει header. Διάβασέ το, αν κάνεις rendering από τον server για πολλά domains από την ίδια διεύθυνση: το καλάθι του ιστότοπου κάθε domain είναι δικό του, αλλά το ανώτατο όριο ανά IP είναι κοινό, και αυτό είναι που φτάνει πρώτο.

Κάνε cache τις απαντήσεις από την πλευρά σου: το ημερήσιο ωροσκόπιο δεν αλλάζει κατά τη διάρκεια της ημέρας, και το cache μέχρι τα μεσάνυχτα λύνει πλήρως το ζήτημα του ορίου.

Πληρωμένο κλειδί σε δημόσια endpoints. Τα /v1/public/* και /v1/embed/* λειτουργούν χωρίς κλειδί, αλλά αν το στείλεις (X-Api-Key), το αίτημα υπολογίζεται με βάση το τιμολόγιό σου, και όχι με βάση την ανώνυμη ποσόστωση, και στην απάντηση δεν υπάρχει δωρεάν υδατογράφημα. Αυτό έχει νόημα για server-side rendering: ένα μηχάνημα εξυπηρετεί όλους τους επισκέπτες, και τα ανώνυμα 300/ώρα δεν του φτάνουν.

Πίνακας κόστους

Πλήρης διαφανής πίνακας με όλα τα 771+ endpoints και το κόστος τους - στη σελίδα Κόστος Endpoints. Οι DivineAPI/AstrologyAPI/Prokerala δεν δημοσιεύουν τέτοιο πίνακα. Σύντομη αναφορά:

Επίπεδο	Πιστώσεις	Τυπικός χρόνος	Παραδείγματα
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	λίγα δευτ.	`/rectification/trutine`
6	500	έως 120 δευτ.	`/rectification`

Headers απάντησης

Κάθε απάντηση περιέχει:

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: πόσες αφαιρέθηκαν για αυτό το αίτημα
X-Credits-Remaining: υπόλοιπο στον μηνιαίο προϋπολογισμό
X-Credits-Limit: συνολικός προϋπολογισμός πιστώσεων ανά μήνα (ανά πλάνο)
X-Credits-Reset: ISO-8601 ημερομηνία ανανέωσης υπολοίπου
X-RateLimit-*: τρέχουσα κατάσταση του sliding window (τυπική μορφή)
- X-RateLimit-Scope: ποιος μετρητής είναι ο πιο περιοριστικός αυτή τη στιγμή: ip, site ή key. Η τιμή key σημαίνει ότι το αίτημα υπολογίστηκε με βάση το κλειδί σου και το όριο του τιμολογίου σου, και όχι με βάση την ανώνυμη ποσόστωση.
- X-RateLimit-Counters: σε δημόσιο endpoint, που καλέστηκε με X-AstroWay-Site-URL, όλοι οι μετρητές με τους οποίους υπολογίστηκε το αίτημα, σε μορφή scope=υπόλοιπο/όριο. Τα παραπάνω headers περιγράφουν μόνο τον πιο περιοριστικό.
- X-RateLimit-Reset: η στιγμή που το παλαιότερο αίτημα θα πέσει από το παράθυρο, δηλαδή όταν θα ελευθερωθεί μία θέση. Αυτός δεν είναι ο χρόνος πλήρους ανοίγματος του bucket: μετά από αυτό θα περάσει ένα αίτημα, και το Reset θα μετατοπιστεί στο επόμενο χρονικά. Ένας client που περιμένει μέχρι το Reset και μετά στέλνει ένα πακέτο, θα λάβει ξανά 429, οπότε είναι πιο αξιόπιστο να στέλνεις ένα αίτημα κάθε φορά ή να κάνεις cache τις απαντήσεις από την πλευρά σου.
- Απορριφθέν αίτημα (429) δεν καταναλώνει ποσόστωση και δεν μετατοπίζει το παράθυρο: ο μετρητής ανανεώνεται μόνο με επιτυχημένα αιτήματα.
- X-RateLimit-Origin-Limit και X-RateLimit-Origin-Remaining: έρχονται μόνο όταν το αίτημα πέρασε με βάση μια καταχώριση από τη λίστα επιτρεπόμενων προελεύσεων, και δείχνουν το μερίδιο που διατέθηκε σε αυτή την καταχώριση. Η απόρριψη λόγω αυτού του μεριδίου είναι επίσης 429, και στο κείμενο αναφέρεται ποια καταχώριση εξαντλήθηκε.
X-Subscription-Status και X-Subscription-Grace-Ends: έρχονται μόνο όταν η πληρωμένη περίοδος έχει ήδη λήξει, αλλά η 3ήμερη περίοδος χάριτος εξακολουθεί να ισχύει (X-Subscription-Status: grace). Τα αιτήματα εξυπηρετούνται με βάση το τιμολόγιό σου μέχρι τη στιγμή στο X-Subscription-Grace-Ends, μετά από αυτήν η απάντηση είναι 402 SUBSCRIPTION_EXPIRED. Αν ο client σου καταγράφει τα headers, αυτό είναι το πιο πρώιμο σήμα ότι το πλάνο πρέπει να ανανεωθεί.
X-Request-Id: αναγνωριστικό αιτήματος, 32 δεκαεξαδικά σύμβολα· ανέφερέ το όταν επικοινωνείς με την υποστήριξη

Πόσα έχουν ήδη δαπανηθεί: τρεις τρόποι

Μπορείς να ελέγξεις το τρέχον υπόλοιπο πιστώσεων με τρεις τρόπους - από τον πιο γρήγορο στον πιο λεπτομερή:

Σε κάθε απάντηση: τα headers X-Credits-Remaining / X-Credits-Used / X-Credits-Limit επιστρέφονται σε οποιοδήποτε αίτημα (ακόμα και σε σφάλμα). Δεν χρειάζεται να καλέσεις κάτι επιπλέον - το υπόλοιπο είναι πάντα μπροστά σου.
Με ξεχωριστό αίτημα: GET /v1/keys/usage με το X-Api-Key σου επιστρέφει credits (used / remaining / limit / reset), usage (αιτήματα για today / week / month) και τα top-20 endpoints για 30 ημέρες. Μία κλήση, χωρίς ξεχωριστό admin-key.
Στο dashboard: api.astroway.info/dashboard/billing δείχνει το υπόλοιπο, το γράφημα χρήσης και την ανάλυση ανά endpoint σε πραγματικό χρόνο.

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

Caching

Πανομοιότυπα αιτήματα εντός 5 λεπτών επιστρέφονται από την cache χωρίς χρέωση πιστώσεων. Αυτό είναι ένα ξεχωριστό header:

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

Τι θεωρείται “πανομοιότυπο”:

Το ίδιο endpoint
Το ίδιο JSON body (byte-προς-byte μετά την κανονικοποίηση των κενών)
Το ίδιο κλειδί API

Αυτό είναι ασφαλές, γιατί όλα τα endpoints είναι ντετερμινιστικά - η ίδια είσοδος δίνει πάντα την ίδια έξοδο.

Streaming και webhooks

Streaming (`/stream/*`)

10 stream-endpoints τιμολογούνται ως Tier 1: 10 πιστώσεις ανά κλήση. Κάθε κλήση υπολογίζει εκ νέου τις θέσεις των πλανητών, οπότε πρόκειται για πλήρη υπολογισμό, και όχι για cached lookup - δεν υπάρχει ξεχωριστή “φθηνότερη” τιμή ανά tick.

Κάθε απάντηση περιέχει δύο πεδία για οικονομική αναζήτηση (polling):

tickSeconds: προτεινόμενο διάστημα αναζήτησης·
nextEventAt: πότε θα αλλάξει η κατάσταση την επόμενη φορά.

Το να κάνεις polling συχνότερα από το tickSeconds - είναι άσκοπο να καις πιστώσεις: η κατάσταση δεν θα αλλάξει μέχρι το nextEventAt.

Webhooks (`/webhooks/*`)

Οι λειτουργίες CRUD διαχείρισης συνδρομής (/webhooks/subscribe, λίστα, προβολή, διαγραφή, /test) κοστίζουν Tier 1: 10 πιστώσεις η καθεμία. Αυτές είναι σπάνιες κλήσεις.

Η παράδοση γεγονότος (server → το URL σου) δεν τιμολογείται: οι πιστώσεις αφαιρούνται μόνο για τις κλήσεις CRUD διαχείρισης. Υποστηρίζονται 12 τύποι γεγονότων (report-ready, transit-alert, eclipse-alert, dasha-change, sign-ingress κ.λπ.).

Τα Webhooks είναι διαθέσιμα από το πλάνο Pro και άνω.

Τι να κάνεις όταν ξεπεραστούν τα όρια

`402 Payment Required`: εξαντλήθηκαν οι πιστώσεις

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

Επιλογές:

Αναβάθμιση πλάνου: αμέσως λαμβάνεις νέο προϋπολογισμό
Overage (Starter/Pro): ενεργοποιείται αυτόματα, αν δεν έχει απενεργοποιηθεί στις ρυθμίσεις
Περίμενε το reset (Free): 1η του επόμενου μήνα

`429 Too Many Requests`: ξεπεράστηκε το RPM

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

Το header Retry-After: 12 - είναι ένα τυπικό HTTP-header, ο HTTP-client σου πρέπει να το κατανοεί.

Σωστή διαχείριση:

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

Εκτίμηση προϋπολογισμού εκ των προτέρων

Πριν την ενσωμάτωση, υπολόγισε πόσες πιστώσεις χρειάζεσαι ανά μήνα:

monthly_credits = daily_active_users × calls_per_user × avg_cost_per_call × 30

Παράδειγμα: εφαρμογή με 500 DAU, κάθε χρήστης κάνει 3 υπολογισμούς χαρτών + 1 συναστρία την ημέρα:

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

Υπολογιστής προϋπολογισμού - στη σελίδα Τιμολόγια.

Στη συνέχεια

Σφάλματα: πλήρης οδηγός κωδικών σφάλματος
Idempotency: πώς να κάνεις επαναλαμβανόμενα αιτήματα με ασφάλεια

Χρήσιμο;

Προτείνετε διόρθωση

Τελευταία ενημέρωση: 5 Οκτ 2026

// Προηγούμενη σελίδα

Γηματρία και τα 72 ονόματα

Επόμενη σελίδα //

Κόστος ανά endpoint