Credits & Rate Limits

AstroWay uses a credit-based model instead of a simple request counter.

Get your API key in 60 seconds

aw_test_demo_aaaa1111

Sign up — free→

This is fairer: lightweight endpoints (/planets) cost 10 credits, heavy ones (/rectification) — 500.

Two kinds of limits

1. Monthly credit budget

Credits per month depend on your plan:

Plan	Credits/mo	Rate limit
Free	10,000	10 req/min
Indie	50,000	30 req/min
Starter	200,000	120 req/min
Pro	800,000	400 req/min
Business	3,500,000	1,000 req/min
Enterprise	Custom	Custom

When credits run out — subsequent requests return 402 Payment Required (Free) or trigger overage billing (Indie+).

2. Rate limit (requests per minute)

Rate limit uses a sliding window. If you fire 120 requests in 10 seconds, the next 50 seconds on that key return 429.

Tip

Rate limit and credit budget are independent. You can have credits but fail rate limit. And vice versa.

3. Public endpoints (no key)

The 14 reference dictionaries /v1/reference/* (signs, planets, houses, aspects, elements, modalities, polarities, dignities, decans, nakshatras, lots, asteroids, zodiac-systems, glyphs) are served publicly without an X-Api-Key and cost 0 credits. Limit — 30 requests / hour per IP. The same data is also exposed as MCP Resources at astroway://reference/<slug> for LLM agents.

The same limit applies to the other public namespaces: /v1/public/*, /v1/embed/*, /v1/i18n/*.

Quota for server-side rendering

30 requests per hour is sized for a browser: every visitor brings their own IP and their own quota. When the calls come from your server instead (a WordPress plugin, SSR, a cache warmer), one address fetches on behalf of every visitor and burns the limit in a handful of page loads.

For that case, send the X-AstroWay-Site-URL header with your site address:

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

Mode	Limit
Without the header	30 requests / hour per IP
With the header	300 requests / hour per site, 600 / hour ceiling per IP

The header is allowed in CORS and is a declaration, not a credential, which is why the IP ceiling stays: however many domains one address names, no more than 600 requests per hour will come out of it. Both counters are needed at once. The site counter binds when one site calls from many addresses (CDN, load balancer); the IP counter binds when many names come from one address.

The X-RateLimit-Scope response header (ip or site) tells you which counter is currently the tightest, and the remaining X-RateLimit-* headers describe that one. Cache responses on your side: a daily horoscope does not change during the day, and caching it until midnight removes the limit question entirely.

A paid key on the public endpoints. /v1/public/* and /v1/embed/* work without a key, but if you send one (X-Api-Key) the request is counted at your plan’s rate instead of the anonymous quota, and the response carries no free-tier watermark. This is what server-side rendering needs: one machine fetches on behalf of every visitor, and the anonymous 300/hour does not stretch that far.

Pricing table

Full transparent per-endpoint table with all 737+ endpoints and their costs — at Per-endpoint Cost. DivineAPI / AstrologyAPI / Prokerala don’t publish anything similar. Quick reference:

Tier	Credits	Typical time	Examples
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	seconds	/rectification/trutine
6	500	up to 120s	/rectification

Response headers

Every response includes:

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-Request-Id: 01HXY2A7ZM...

• X-Credits-Used — credits charged for this request
• X-Credits-Remaining — remainder of monthly budget
• X-Credits-Limit — full monthly credit budget (per plan)
• X-Credits-Reset — ISO-8601 balance reset date
• X-RateLimit-* — current sliding window state (standard format)
  • X-RateLimit-Scope — which counter is currently the tightest: ip, site or key. A value of key means the request was counted against your key at your plan’s rate, not against the anonymous quota.
  • X-RateLimit-Reset — when the oldest request leaves the window, i.e. when one slot frees up. It is not the moment the whole bucket reopens: one request goes through after it, then Reset moves to the next timestamp. A client that waits for Reset and then sends a burst gets a 429 again, so send one request at a time or cache on your side.
  • A rejected request (429) does not spend quota and does not move the window: only successful requests fill the counter.
• X-Request-Id — ULID for this request, use in support requests

Checking your usage — three ways

You can check your current credit balance three ways — from fastest to most detailed:

1. On every response — the X-Credits-Remaining / X-Credits-Used / X-Credits-Limit headers come back on any request (even errors). Nothing extra to call — your balance is always in front of you.
2. On demand — GET /v1/keys/usage with your X-Api-Key returns credits (used / remaining / limit / reset), usage (requests for today / week / month), and your top-20 endpoints over 30 days. One call, no separate admin key.
3. In the dashboard — api.astroway.info/dashboard/billing shows your balance, a usage chart, and a per-endpoint breakdown in real time.

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

Tip

Unlike most APIs (Anthropic, OpenAI), AstroWay returns your remaining balance right in the header of every response (X-Credits-Remaining) — no need to open a dashboard or a separate usage API to find out how much is left.

Caching

Identical requests within 5 minutes return from cache without consuming credits. This is a separate header:

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

What counts as “identical”:

• Same endpoint
• Same JSON body (byte-for-byte after whitespace normalization)
• Same API key

This is safe because all endpoints are deterministic — same input always produces same output.

Streaming and webhooks

Streaming (/stream/*)

The 10 streaming endpoints are priced as Tier 1 — 10 credits per call. Each call recomputes planetary positions, so it is a live compute, not a cached lookup — there is no discounted “per-tick” rate.

Every response carries two fields for efficient polling:

• tickSeconds — recommended poll interval;
• nextEventAt — when the state next changes.

Polling faster than tickSeconds burns credits for nothing: the state won’t change until nextEventAt.

Caution

Budget example: one stream polled every 60 s = 1,440 calls/day × 10 credits = 14,400 credits/day ≈ 3.5 days of one stream on Indie (50,000/mo). For continuous streaming, use Starter+.

Webhooks (/webhooks/*)

Subscription-management CRUD calls (/webhooks/subscribe, list, get, delete, /test) cost Tier 1 — 10 credits each. These are made rarely.

Webhook delivery (server → your URL) is not billed — credits are charged only for the CRUD management calls. 12 event types are supported (report-ready, transit-alert, eclipse-alert, dasha-change, sign-ingress, etc.).

Webhooks are available on the Pro plan and above.

What to do when limits are hit

402 Payment Required — out of credits

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

Options:

• Upgrade plan — immediate new budget
• Overage (Starter/Pro) — auto-enabled unless disabled in settings
• Wait for reset (Free) — 1st of next month

429 Too Many Requests — RPM exceeded

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

Retry-After: 12 header — standard HTTP, your HTTP client should understand it.

Correct handling:

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

Caution

Don’t do exponential backoff without a cap — the Retry-After header already contains the exact number. Trust it.

Budget estimation in advance

Before integrating, estimate monthly credits:

monthly_credits = daily_active_users × calls_per_user × avg_cost_per_call × 30

Example: app with 500 DAU, each making 3 chart calculations + 1 synastry per day:

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

Budget calculator — on the Pricing page.

Next

• Errors — full error code reference
• Idempotency — how to retry safely