Developer Guide: Astrology API Authentication and Rate Limits

Building with an astrology API means handling authentication, managing credits, and respecting rate limits correctly from day one. Get any of these wrong and your app will see intermittent failures, surprise 429 errors, or — worst case — a leaked API key on a public repository. This guide covers everything you need to ship a reliable integration: how API key authentication works, how the credit system maps to endpoints, how rate limits scale by plan, and how to handle every error status code with clean, production-ready JavaScript.

API Key Authentication

Every request to the GitStrology API must include a valid API key. The key is passed in the X-API-Key header. Keys follow the format gs_live_<48 hex characters> and are tied to your account and billing plan. Without a valid key, every endpoint returns a 401 Unauthorized response.

curl "https://api.gitstrology.dev/v1/horoscope" \
  -H "X-API-Key: gs_live_xxxxx" \
  -H "Content-Type: application/json" \
  -d '{"sign":"aries"}'

Creating an API Key

Generate keys from the dashboard. When you create a key, the full secret value is shown exactly once — copy it immediately, because it is stored as a one-way SHA-256 hash and cannot be recovered later. If you lose a key, you must revoke it and create a new one. This design means even a database breach on GitStrology's side cannot expose your raw key.

Key Security Best Practices

A leaked API key lets anyone spend your credits or exhaust your rate limit. Treat keys with the same care as database passwords:

• Never commit keys to git. Add .env to your .gitignore file and use a secrets manager for production deployments.
• Always use environment variables. Reference keys as process.env.GITSTROLOGY_API_KEY so they never appear in source code.
• Rotate keys regularly. Create a new key, deploy your app with the new value, confirm traffic flows, then revoke the old key.
• Use separate keys per environment. One key for development, one for staging, one for production. This isolates blast radius if a dev key leaks.
• Revoke compromised keys immediately. Do not wait — a revoked key stops all unauthorized traffic instantly.

For the full authentication reference, see the authentication docs. If you are just getting started, the quickstart guide walks through creating your first key and making your first request.

The Credit System Explained

GitStrology uses a credit-based pricing model. Every API request consumes a fixed number of credits based on the computational cost of the endpoint. Your monthly credit budget is determined by your plan. When you run out of credits, further requests return a 402 Payment Required error until your monthly allocation resets or you upgrade.

The credit cost per endpoint is:

• /v1/horoscope — 1 credit
• /v1/moon-phase — 1 credit
• /v1/sun-sign — 1 credit
• /v1/numerology — 2 credits
• /v1/tarot — 3 credits
• /v1/natal-chart — 5 credits
• /v1/compatibility — 5 credits
• /v1/transits — 5 credits

Lightweight lookups (horoscope, moon phase, sun sign) cost 1 credit, while compute-heavy astrological calculations (natal charts, compatibility, transits) cost 5. This keeps simple features nearly free while pricing complex ephemeris work honestly. The complete cost table lives on the rate limits and credits page.

Rate Limits by Plan

In addition to monthly credit budgets, every plan enforces a per-minute request rate limit. Rate limiting protects the shared infrastructure and ensures fair access for all users. The limits scale with your plan tier:

• Free — 10 requests/minute
• Pro — 60 requests/minute
• Business — 120 requests/minute
• Enterprise — 300 requests/minute

Rate limits are independent of credits. Even if you have 50,000 credits remaining, exceeding your plan's requests-per-minute cap returns a 429 Too Many Requests response. Responses include two headers to help you self-regulate: X-RateLimit-Limit (your per-minute allowance) and X-RateLimit-Remaining (requests left in the current minute window).

Credit Allocation by Plan

Your monthly credit budget grows substantially as you move up tiers. The current plans are:

• Free — 100 credits/month, $0
• Pro — 10,000 credits/month, $19/month
• Business — 50,000 credits/month, $49/month
• Enterprise — 200,000 credits/month, $99/month

To put that in perspective, the free tier's 100 credits covers roughly 100 horoscope lookups, 33 tarot draws, or 20 natal charts per month — enough to prototype and test. The Pro tier's 10,000 credits supports a small production app serving daily horoscopes to about 300 users every day. Compare plans in detail on the pricing page.

The Response Envelope

Every successful response is wrapped in a standard envelope that includes both the payload data and a real-time credit summary. This lets you monitor usage without a separate billing API call:

{
  "data": {
    "date": "2026-08-03",
    "sign": "aries",
    "mood": "ambitious",
    "energy": 4,
    "luck": 3,
    "love": 5,
    "career": 4,
    "summary": "Aries energy is running high today..."
  },
  "credits": {
    "used": 1,
    "remaining": 9999
  }
}

The credits.used field shows how many credits the current request consumed, and credits.remaining shows your remaining monthly balance. Track these values client-side to surface usage warnings to your users before they hit a hard stop.

Using the SDK

The official TypeScript SDK handles authentication and credit tracking automatically. Initialize it once with your key and the header is applied to every request:

import { Gitstrology } from "gitstrology";

const gs = new Gitstrology({ apiKey: process.env.GITSTROLOGY_API_KEY });

const horoscope = await gs.horoscope({ sign: "aries" });
console.log(horoscope.data.summary);
console.log(horoscope.credits.remaining);

Error Handling

Three HTTP status codes cover the vast majority of auth and quota failures. Every error response uses a consistent JSON shape so you can parse it uniformly:

{
  "error": {
    "code": "insufficient_credits",
    "message": "You have used all 100 credits on the free plan this month."
  }
}

401 Unauthorized — Invalid or Missing Key

A 401 means the X-API-Key header was missing, malformed, or has been revoked. Check that your environment variable is set and that the key still exists in the dashboard.

429 Too Many Requests — Rate Limited

A 429 means you exceeded your plan's per-minute request limit. The response body tells you which limit was hit. Implement exponential backoff and retry — the limit resets at the start of the next minute window.

402 Payment Required — Insufficient Credits

A 402 means you have exhausted your monthly credit budget. Further requests will fail until the budget resets or you upgrade your plan.

A Complete Error Handling Example

Here is a production-ready wrapper that catches all three status codes and responds intelligently, including exponential backoff for rate-limit errors:

import { Gitstrology } from "gitstrology";

const gs = new Gitstrology({ apiKey: process.env.GITSTROLOGY_API_KEY! });

async function safeHoroscope(sign: string, retries = 3) {
  try {
    const result = await gs.horoscope({ sign });
    return { ok: true, data: result.data, credits: result.credits };
  } catch (err: any) {
    const status = err.response?.status;
    const code = err.response?.data?.error?.code;
    const message = err.response?.data?.error?.message;

    if (status === 401) {
      // Invalid or missing API key — do not retry, surface to user
      console.error("Auth failed:", message);
      return { ok: false, error: "API key is invalid or missing." };
    }

    if (status === 402) {
      // Out of credits — prompt upgrade, do not retry
      console.error("No credits remaining:", message);
      return { ok: false, error: "Monthly credit limit reached." };
    }

    if (status === 429 && retries > 0) {
      // Rate limited — back off and retry
      const waitMs = Math.pow(2, 4 - retries) * 1000;
      console.warn(`Rate limited. Retrying in ${waitMs}ms...`);
      await new Promise((r) => setTimeout(r, waitMs));
      return safeHoroscope(sign, retries - 1);
    }

    if (status === 429) {
      return { ok: false, error: "Rate limit exceeded. Please slow down." };
    }

    // Unexpected error
    console.error("Unexpected error", code, message);
    return { ok: false, error: "Something went wrong." };
  }
}

const result = await safeHoroscope("aries");
if (result.ok) {
  console.log(result.data.summary);
} else {
  console.log(result.error);
}

Monitoring Your Credit Balance

Because every response includes the credits.remaining field, you can track usage passively without extra API calls. A common pattern is to log the remaining balance and alert when it drops below a threshold:

const LOW_CREDIT_THRESHOLD = 500;

if (result.credits.remaining < LOW_CREDIT_THRESHOLD) {
  console.warn(
    `Low credits: ${result.credits.remaining} remaining this month.`
  );
  // Trigger an alert to your monitoring system
}

For a deeper dive into rate limit headers and the complete credit cost table, see the rate limits documentation.

Key Takeaways

• Authenticate every request with the X-API-Key header using a key in the format gs_live_xxxxx.
• Create keys in the dashboard; the full secret is shown only once and is stored as an irreversible SHA-256 hash.
• Never commit keys to git — use environment variables, rotate keys regularly, and use separate keys per environment.
• Credits are consumed per request: horoscope/moon-phase/sun-sign cost 1, numerology costs 2, tarot costs 3, and natal-chart/compatibility/transits cost 5.
• Rate limits by plan: Free = 10 req/min, Pro = 60, Business = 120, Enterprise = 300.
• Monthly credits by plan: Free = 100, Pro = 10,000 ($19), Business = 50,000 ($49), Enterprise = 200,000 ($99).
• Every response includes credits.used and credits.remaining for real-time usage tracking.
• Handle three error codes: 401 (invalid key), 429 (rate limited — back off and retry), and 402 (out of credits — upgrade plan).
• Full references live in the authentication docs and rate limits docs. Compare tiers on the pricing page.

Ready to build? Grab your API key, follow the quickstart, and ship a reliable astrology integration today.