API authentication and rate limits

Send your key

Every request needs your API key. Send it in one of these two headers:

Authorization: Bearer YOUR_API_KEY
X-API-Key: YOUR_API_KEY

Use Authorization if you can. It is the standard bearer token header from RFC 6750. Use X-API-Key if your HTTP client or proxy will not let you set Authorization. Send requests to https://apiforastrology.com/api/astrology.

curl "https://apiforastrology.com/api/astrology/v1/meta" \
  -H "Authorization: Bearer $ASTROLOGY_API_KEY"

Get and manage keys

Create and manage keys on the API keys page of your account. The full key is shown once, when you create it. Use a test key (afa_test_) while you build and a live key (afa_live_) in production. Both call the same API and get the same real results. Test calls are free and never count toward your plan’s monthly quota.

Each key ends with a short checksum, so a mistyped key is refused at once. Keys made before October 3, 2026 start with ak_ and keep working.

Owners and admins can do three things with each key:

• Disable pauses the key. Calls with it get 401 key_disabled. Enable it again at any time. Use this when something looks odd and you want to check first.
• Roll gives you a new key with the same name and type. The old key keeps working for 24 hours, so you can deploy the new one with no downtime. After that, the old key gets 401 key_expired.
• Revoke ends the key for good. Calls with it get 401 key_revoked. This cannot be undone.

Each key shows its history: who created, paused, rolled or revoked it, and when. It also shows where the key was used from in the last 30 days. You see the top countries, about how many IP addresses, and whether a browser called it. Owners get an email when a key is paused, rolled or revoked.

Keep your key safe

Anyone who has your key can use up your plan. A few habits keep it safe:

• Call the API from your server only. Never put a key in front-end code, a web page or a mobile app, where anyone can copy it.
• Never put a key in an AI prompt either. A chatbot calls the API through a tool handler on your server, as the AI assistants guide shows.
• Keep keys out of code. Read the key from an environment variable, such as ASTROLOGY_API_KEY. Never commit it to a repository, public or private.
• Use one key per app. For example, Acme Inc. might use one key for its website and another for its mobile app backend. Then it can roll one key without touching the other.
• Roll your keys when someone who had access leaves your team.
• If a key leaks, roll it, deploy the new key, then revoke the old one. If you are not sure, disable it first while you check.

We also watch for leaks for you:

• If a web browser on another website calls one of your live keys, we email your account owners. They get at most one email a week for each key. We also show a warning on the API keys page. The key keeps working, but it should move to your server. Test keys are not checked.

Rate limits and quotas

Every plan can call every endpoint. Calculations use calls, and written readings use reading credits. Plans differ only in their limits. Live keys have three:

• A rate limit for each key. Each live key can make the plan’s number of calls per minute. Every key has its own count, so one busy key does not slow down your other keys. Every call counts as 1, a full report too.
• Monthly calls for your account. All your live keys share them. Every successful calculation uses 1 call. The calls reset on the 1st of each month (UTC). When the calls run out, calls already in progress still finish. Any calls over the limit come off next month’s calls.
• Monthly reading credits. Written readings use credits instead of calls (below). You can never use more credits than you have for the month.

Responses to requests that pass the key check carry these headers:

• X-RateLimit-Limit: how many calls this key may make per minute.
• X-RateLimit-Remaining: how many this key has left this minute.
• X-RateLimit-Reset: seconds until the minute ends and the count starts again.
• X-Calls-Counted: calls this response used. 0 for errors and for written readings on live keys.
• X-Reading-Credits-Counted: reading credits this response used. Only on written readings.
• X-Reading-Credits-Remaining: reading credits left this month. Only on written readings with a live key.

Reading credits

A written reading uses reading credits from your monthly allowance. It uses no calls. A reading costs the same credits in every language, and at standard or longer length. Failed requests use nothing. When a reading needs more credits than are left, it gets 429 reading_credits_exceeded.

The same key calls the Numerology API. Every numerology answer is a written reading, so each endpoint uses reading credits from the same allowance, and no calls:

See pricing for each plan’s credits, and what a call costs on each plan.

Test keys

Test keys have their own small limits on every plan, and they are never billed. Each test key can make 10 calls a minute. All your test keys together can make 1,000 calls a month. Every successful test call counts as 1, readings included, and never uses your live calls or credits.

Test keys return calculations for any chart, but written readings only for the two sample charts in these docs. Any other chart gets 403 sample_charts_only. Send the birth details exactly as below. On calls about a couple, both people must be sample charts. The daily sign horoscope works for the sample charts’ Moon signs, Taurus and Scorpio. A Moon sign is the sign the Moon was in at birth. Readings work for today, or for the date in the docs examples: October 1, 2026. For the annual forecast and the varshaphal, that is the year 2026. The weekly reading needs a start date, so send from=2026-10-01.

{
  "year": 1990,
  "month": 8,
  "day": 15,
  "hour": 10,
  "minute": 30,
  "second": 0,
  "latitude": 40.7128,
  "longitude": -74.006,
  "timezone": "America/New_York"
}

{
  "year": 1992,
  "month": 3,
  "day": 22,
  "hour": 14,
  "minute": 45,
  "second": 0,
  "latitude": 41.8781,
  "longitude": -87.6298,
  "timezone": "America/Chicago"
}

The Numerology API takes the same test keys. Every numerology answer is a reading, so a test key answers only for the sample people: John Doe, born Aug 15, 1990, and Jane Doe, born Mar 22, 1992. Send their names and birth dates as they are. A business name must be Acme Inc., and a surname must be Doe. Leave dates out for today, or send the docs’ dates, such as as_of 2026-10-01. GET /v1/guide/{number} and GET /v1/year/{mulank} take 6 or 4, their mulanks (birth day numbers). The baby name finder takes the starting letter J only. Anything else gets 403 sample_charts_only. A name in another script gets the same 422 as on a live key.

See pricing for higher limits.

401 Unauthorized

The key does not work. The code says why:

• unauthorized: the key is missing, mistyped or unknown.
• key_disabled: the key is paused. An owner or admin can enable it on the API keys page, or roll it if it leaked.
• key_expired: the key was rolled more than 24 hours ago. Use the new key.
• key_revoked: the key was revoked. Create a new key.

Fix the key before you retry. The same key will fail the same way.

HTTP/1.1 401 Unauthorized
WWW-Authenticate: Bearer
Content-Type: application/json

{"error": {"code": "key_disabled", "message": "This API key is paused. An owner or admin of your account can enable it again on the API keys page, or roll it to get a new key."}}

429 Too Many Requests

You went over a limit. The code says which one:

• rate_limited: this key made too many calls this minute. Your other keys are not affected.
• quota_exceeded: your live keys used up this month’s calls.
• reading_credits_exceeded: this written reading needs more reading credits than are left this month. Calculations still work.
• test_quota_exceeded: your test keys used up this month’s free test calls. Live keys are not affected.

Wait the number of seconds in Retry-After, then try again. After a monthly limit, that is the time until the 1st of the next month (UTC). The errors guide has a short retry function in JavaScript. If you hit a limit often, spread your requests out or move to a bigger plan.

HTTP/1.1 429 Too Many Requests
Retry-After: 21
X-RateLimit-Limit: 250
X-RateLimit-Remaining: 0
X-RateLimit-Reset: 21
Content-Type: application/json

{"error": {"code": "rate_limited", "message": "Rate limit of 250 calls per minute for this key exceeded. Each key has its own limit."}}