Crediti e limiti

AstroWay utilizza un modello a crediti anziché un semplice contatore di richieste.

Ottieni la tua chiave API in 60 secondi

aw_test_demo_aaaa1111

Registrati - gratis→

Questo è più equo: gli endpoint leggeri (/planets) costano 10 crediti, quelli pesanti (/rectification) - 500.

Due tipi di limiti

1. Budget crediti giornaliero/mensile

Il numero di crediti al mese dipende dal piano:

Piano	Crediti/mese	Limite giornaliero
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

Una volta esauriti i crediti, le richieste successive restituiscono 402 Payment Required (Free) o attivano la fatturazione overage (Indie+).

2. Rate limit (richieste al minuto)

Piano	RPM
Free	10 req/min
Indie	30 req/min
Starter	120 req/min
Pro	400 req/min
Business	1 000 req/min
Enterprise	Custom

Il rate limit è una sliding window. Se hai inviato 120 richieste in 10 secondi, i successivi 50 secondi con quella chiave riceverai 429.

Consiglio

Rate limit e budget crediti sono indipendenti. Puoi avere crediti ma non superare il rate limit. E viceversa.

Se una chiave ha un elenco di origini consentite, ogni voce dell’elenco riceve la sua quota di questo limite: il limite della chiave diviso per il numero di voci, arrotondato per eccesso. Un singolo sito con un widget incorporato non può, per questo motivo, consumare la quota pagata dal proprietario della chiave, lasciando gli altri suoi domini operativi. Il limite totale della chiave non aumenta: le quote lo dividono, non si aggiungono ad esso.

Il contatore è basato sulla voce, non sull’host di provenienza. La voce *.example.com è un unico contatore per tutti i sottodomini, altrimenti la limitazione verrebbe aggirata inventando un nuovo sottodominio per ogni richiesta. Quando c’è una sola voce nell’elenco, la quota è uguale al limite e nulla cambia.

3. Endpoint pubblici (senza chiave)

14 dizionari di riferimento /v1/reference/* (signs, planets, houses, aspects, elements, modalities, polarities, dignities, decans, nakshatras, lots, asteroids, zodiac-systems, glyphs) sono serviti pubblicamente, senza X-Api-Key e costano 0 crediti. Il limite è di 30 richieste/ora da un singolo IP. Gli stessi dati sono esposti come MCP Resources astroway://reference/<slug> per gli agenti LLM.

Lo stesso limite si applica al resto dei namespace pubblici: /v1/public/*, /v1/embed/*, /v1/i18n/*.

Quota per il rendering lato server

30 richieste all’ora sono calcolate per il browser: ogni visitatore porta il proprio IP e la propria quota. Se invece le richieste sono effettuate dal tuo server (plugin WordPress, SSR, riscaldamento della cache), un singolo indirizzo agisce per tutti i visitatori ed esaurisce il limite in pochi ricaricamenti di pagina.

Per questo caso, invia l’header X-AstroWay-Site-URL con l’indirizzo del sito:

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

Modalità	Limite
Senza header	30 richieste/ora per IP; i widget /v1/embed/* hanno un limite separato di 120/ora per IP
Con header	300 richieste/ora per sito, tetto massimo 600/ora per IP

L’header è consentito in CORS e non è una credenziale, quindi il tetto massimo per IP rimane: non importa quanti domini vengano chiamati da un singolo indirizzo, in totale non verranno inviate più di 600 richieste all’ora. Entrambi i contatori sono necessari contemporaneamente: il contatore del sito si attiva quando un sito effettua richieste da molti indirizzi (CDN, bilanciatore), il contatore IP si attiva quando molti nomi provengono da un singolo indirizzo.

Una singola chiamata non è sempre una singola unità. Un endpoint pubblico pesante consuma di più dallo stesso “cestino”, anziché riceverne uno separato. POST /v1/public/synastry costa 3, perché sono due carte e una matrice di aspetti di 45 celle: il tetto pratico per esso è 10 all’ora da un indirizzo non dichiarato, 100 per un sito dichiarato e 200 per indirizzo. Tutto il resto costa 1. Quando una chiamata costa più di un’unità, la risposta lo indica nell’header X-RateLimit-Cost, e una chiamata che costa più di quanto rimasto nel “cestino” viene rifiutata, anziché andare in negativo.

Quale contatore è attualmente il più restrittivo, lo indica l’header della risposta X-RateLimit-Scope (ip o site). Il resto degli header X-RateLimit-* descrivono solo quello, cioè solo uno dei due contatori. Il secondo è visibile in X-RateLimit-Counters:

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

Il formato è scope=rimanente/limite separato da virgola. L’header arriva solo quando ci sono effettivamente due contatori: una chiamata anonima con X-AstroWay-Site-URL. Una chiamata con una chiave a pagamento viene conteggiata in base alla tua chiave e alla tua tariffa, lì c’è un solo contatore e nessun header. Leggilo se stai renderizzando da server più domini dallo stesso indirizzo: il “cestino” del sito è proprio di ogni dominio, ma il tetto massimo per IP è condiviso, ed è quello che si esaurisce per primo.

Metti in cache le risposte dal tuo lato: l’oroscopo giornaliero non cambia durante il giorno, e una cache fino a mezzanotte risolve completamente la questione del limite.

Chiave a pagamento sugli endpoint pubblici. /v1/public/* e /v1/embed/* funzionano senza chiave, ma se la trasmetti (X-Api-Key), la richiesta viene conteggiata in base alla tua tariffa, non alla quota anonima, e la risposta non contiene la filigrana gratuita. Questo ha senso per il rendering server-side: una singola macchina agisce per tutti i visitatori, e 300/ora anonimi sono pochi per essa.

Tabella dei costi

Una tabella completa e trasparente con tutti gli 771+ endpoint e i loro costi è disponibile sulla pagina Costo degli endpoint. DivineAPI/AstrologyAPI/Prokerala non pubblicano una tale tabella. Un breve riferimento:

Tier	Crediti	Tempo tipico	Esempi
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	alcuni s	/rectification/trutine
6	500	fino a 120 s	/rectification

Header della risposta

Ogni risposta contiene:

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: quanti crediti sono stati detratti per questa richiesta
• X-Credits-Remaining: saldo rimanente sul budget mensile
• X-Credits-Limit: budget totale di crediti al mese (secondo il piano)
• X-Credits-Reset: data ISO-8601 di reset del saldo
• X-RateLimit-*: stato attuale della sliding window (formato standard)
  • X-RateLimit-Scope: quale contatore è attualmente il più restrittivo: ip, site o key. Il valore key significa che la richiesta è stata conteggiata in base alla tua chiave e al limite della tua tariffa, non alla quota anonima.
  • X-RateLimit-Counters: su un endpoint pubblico, chiamato con X-AstroWay-Site-URL, tutti i contatori per i quali la richiesta è stata conteggiata, nel formato scope=rimanente/limite. Gli header sopra descrivono solo il più restrittivo.
  • X-RateLimit-Reset: il momento in cui la richiesta più vecchia uscirà dalla finestra, cioè quando si libererà uno slot. Questo non è il tempo di apertura completa del bucket: dopo di esso passerà una richiesta, e Reset si sposterà al successivo in ordine di tempo. Un client che attende fino a Reset e poi invia un batch riceverà di nuovo 429, quindi è più affidabile procedere con una richiesta alla volta o mettere in cache le risposte dal tuo lato.
  • Una richiesta rifiutata (429) non consuma quota e non sposta la finestra: il contatore si ricarica solo con richieste riuscite.
  • X-RateLimit-Origin-Limit e X-RateLimit-Origin-Remaining: arrivano solo quando la richiesta è passata per una voce dall’elenco delle origini consentite, e mostrano la quota assegnata a quella specifica voce. Un rifiuto per questa quota è anch’esso 429, e nel testo viene specificato quale voce è stata esaurita.
• X-Subscription-Status e X-Subscription-Grace-Ends: arrivano solo quando il periodo pagato è già terminato, ma il periodo di grazia di 3 giorni è ancora in corso (X-Subscription-Status: grace). Le richieste vengono servite secondo la tua tariffa fino al momento indicato in X-Subscription-Grace-Ends, dopo di che la risposta sarà 402 SUBSCRIPTION_EXPIRED. Se il tuo client registra gli header, questo è il segnale più precoce che è ora di rinnovare il piano.
• X-Request-Id: identificatore della richiesta, 32 caratteri esadecimali; forniscilo quando contatti il supporto

Quanto è già stato speso: tre modi

Puoi controllare il saldo crediti attuale in tre modi - dal più veloce al più dettagliato:

1. In ogni risposta: gli header X-Credits-Remaining / X-Credits-Used / X-Credits-Limit vengono restituiti per qualsiasi richiesta (anche in caso di errore). Non è necessario chiamare nulla in più - il saldo è sempre sotto i tuoi occhi.
2. Con una richiesta separata: GET /v1/keys/usage con la tua X-Api-Key restituisce credits (used / remaining / limit / reset), usage (richieste per today / week / month) e i primi 20 endpoint degli ultimi 30 giorni. Una singola chiamata, senza una chiave admin separata.
3. Nella dashboard: api.astroway.info/dashboard/billing mostra il saldo, il grafico di utilizzo e la ripartizione per endpoint in tempo reale.

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

Consiglio

A differenza della maggior parte delle API (Anthropic, OpenAI), AstroWay restituisce il saldo rimanente direttamente nell’header di ogni risposta (X-Credits-Remaining) - non è necessario andare nella dashboard o in un’API di utilizzo separata per sapere quanto è rimasto.

Caching

Richieste identiche entro 5 minuti vengono restituite dalla cache senza detrazione di crediti. Questo è un header separato:

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

Cosa si considera “identico”:

• Lo stesso endpoint
• Lo stesso JSON body (byte-per-byte dopo la normalizzazione degli spazi)
• La stessa chiave API

Questo è sicuro, perché tutti gli endpoint sono deterministici - lo stesso input produce sempre lo stesso output.

Streaming e webhook

Streaming (/stream/*)

10 endpoint di streaming sono tariffati come Tier 1: 10 crediti per chiamata. Ogni chiamata ricalcola le posizioni dei pianeti, quindi è un calcolo completo, non una ricerca in cache - non esiste una tariffa “più economica” separata per tick.

Ogni risposta contiene due campi per un polling economico:

• tickSeconds: intervallo di polling raccomandato;
• nextEventAt: quando lo stato cambierà la prossima volta.

Effettuare il polling più frequentemente di tickSeconds è uno spreco di crediti: lo stato non cambierà prima di nextEventAt.

Attenzione

Esempio di budget: un singolo stream, interrogato ogni 60 s = 1.440 chiamate/giorno × 10 crediti = 14.400 crediti/giorno. Con Indie (50.000/mese) sono circa 3,5 giorni di un singolo stream. Per lo streaming continuo - Starter+.

Webhook (/webhooks/*)

Le operazioni CRUD di gestione dell’abbonamento (/webhooks/subscribe, elenco, visualizzazione, eliminazione, /test) costano Tier 1: 10 crediti ciascuna. Queste sono chiamate rare.

La consegna dell’evento (server → il tuo URL) non è tariffata: i crediti vengono detratti solo per le chiamate CRUD di gestione. Sono supportati 12 tipi di eventi (report-ready, transit-alert, eclipse-alert, dasha-change, sign-ingress, ecc.).

I webhook sono disponibili a partire dal piano Pro e superiori.

Cosa fare in caso di superamento dei limiti

402 Payment Required: crediti esauriti

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

Opzioni:

• Upgrade del piano: ricevi immediatamente un nuovo budget
• Overage (Starter/Pro): si attiva automaticamente, se non disabilitato nelle impostazioni
• Attendere il reset (Free): il 1° del mese successivo

429 Too Many Requests: RPM superato

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

L’header Retry-After: 12 è un header HTTP standard, il tuo client HTTP dovrebbe capirlo.

Gestione corretta:

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

Attenzione

Non fare un backoff esponenziale senza un cap - Retry-After nella risposta contiene già il numero esatto. Fidati di esso.

Stima del budget in anticipo

Prima dell’integrazione, stima quanti crediti ti servono al mese:

monthly_credits = daily_active_users × calls_per_user × avg_cost_per_call × 30

Esempio: un’applicazione con 500 DAU, ogni utente effettua 3 calcoli di carte + 1 sinastria al giorno:

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

Il calcolatore del budget è disponibile sulla pagina Tariffe.

Avanti

• Errori: guida completa ai codici di errore
• Idempotenza: come effettuare richieste ripetute in sicurezza