Rate Limits

Rate-Limiting Behavior

The API applies usage limits to protect stability and fairness. When limits are exceeded, the API responds with 429 and includes retry guidance.

Header Behavior (Exact)

Case	Headers Returned
Normal authenticated responses (2xx/4xx like 422)	`X-RateLimit-Limit`, `X-RateLimit-Remaining`, `X-RateLimit-Reset`
`429 rate_limit_exceeded` (daily/monthly quota)	`X-RateLimit-Limit`, `X-RateLimit-Remaining`, `X-RateLimit-Reset`, `Retry-After`
`429 rps_limit_exceeded` / `429 abuse_penalty_active`	`Retry-After` (RPS-specific JSON fields are in body)
Replayed idempotent response	`Idempotency-Replayed: true`

429 Error Types

error	Meaning	What to do
rps_limit_exceeded	Per-second request rate exceeded.	Wait `Retry-After` and retry with jitter. JSON includes `retry_after_ms`, `backoff_hint`, `tier_rps_limit`, `penalty_active`.
abuse_penalty_active	Temporary penalty window is active after repeated bursts.	Do not spam retries; wait full penalty window.
rate_limit_exceeded	Plan/day/month quota reached.	Wait until reset or upgrade plan.
idempotency_key_reused	Same `Idempotency-Key` was reused with a different method, path, query, or body.	Generate a new key for the new operation. HTTP status is `409`.
request_in_progress	A matching request with the same key is still running.	Wait `Retry-After` and retry with the same key. HTTP status is `409`.

Safe Retries with Idempotency-Key

Authenticated, billable astrology POST requests accept the optional header Idempotency-Key: <client-generated unique operation key>. Use it when retrying a request that may have timed out after reaching the API.

Same method, path, query string, body, and key returns the first completed response with Idempotency-Replayed: true. Replays do not rerun the calculation and do not consume extra quota.

Keys are retained for about 24 hours. Requests without this header keep the existing behavior unchanged.

Recommended Client Retry Strategy

Always honor Retry-After if present.
Use exponential backoff with full jitter.
Base delay: 250ms, max delay: 5s.
For billable POST retries, reuse the same Idempotency-Key only for the exact same request.
Set a retry cap to avoid infinite retry loops.

Important Notes

Do not retry immediately in tight loops after a 429.
Repeated bursts can trigger temporary blocking windows.
Server-side limits are enforced even if client-side throttling exists.

Reference

Base URL: https://api.freeastroapi.com

This page is the target returned by throttling responses in the docs field.