Credits & Rate Limits

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

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.

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.

Pricing table

Full transparent per-endpoint table with all 723+ 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-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:

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.
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.
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"

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.

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

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.

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

Was this helpful?

Suggest an edit

Last updated: Jun 17, 2026