Rate Limits

Understand AstroCal's rate limiting, usage quotas, and how to handle 429 responses.

AstroCal uses dual-layer rate limiting to protect the API and ensure fair usage across all customers.

Rate Limit Tiers

Each plan has per-minute and daily rate limits:

Plan	Requests/Minute	API Calls/Day
Free	60	500
Launch	100	1,000
Grow	1,000	10,000
Scale	5,000	100,000

Rate Limit Headers

Every authenticated API response includes rate limit headers:

Header	Description
`X-RateLimit-Limit`	Maximum requests per minute for your plan
`X-RateLimit-Remaining`	Remaining requests in the current minute window
`X-RateLimit-Reset`	ISO 8601 timestamp when the current window resets
`Retry-After`	Seconds to wait before retrying (only on 429 responses)

curl -i https://api.astrocal.dev/v1/event-types \
  -H "Authorization: Bearer YOUR_API_KEY"

# Response headers:
# X-RateLimit-Limit: 100
# X-RateLimit-Remaining: 97
# X-RateLimit-Reset: 2026-02-17T14:30:00.000Z

Handling 429 Responses

When you exceed a rate limit, the API returns a 429 Too Many Requests response:

{
  "error": {
    "code": "rate_limit_exceeded",
    "message": "Rate limit exceeded. Your limit is 100 requests/minute (Launch tier).",
    "limit": 100,
    "window": "1m",
    "reset_at": "2026-02-17T14:30:00.000Z",
    "retry_after": 45,
    "tier": "launch"
  }
}

The window field indicates which limit was exceeded:

"1m" — per-minute burst limit
"24h" — daily quota limit

Best practices for handling rate limits:

Check the Retry-After header and wait before retrying
Implement exponential backoff for repeated 429 responses
Monitor the X-RateLimit-Remaining header to proactively slow down before hitting limits

Exempt Operations

The following operations are not counted against your rate limits:

GET /v1/bookings/:id — viewing a booking
POST /v1/bookings/:id/cancel — cancelling a booking
POST /v1/bookings/:id/reschedule — rescheduling a booking
GET /v1/usage — checking your usage
GET /v1/usage/summary — usage summary metrics
GET /health — health check
GET /v1/openapi.json — OpenAPI spec

Checking Your Usage

Use the GET /v1/usage endpoint to check your current plan limits and usage:

curl https://api.astrocal.dev/v1/usage \
  -H "Authorization: Bearer YOUR_API_KEY"

{
  "tier": "launch",
  "limits": {
    "api_calls_per_minute": 100,
    "api_calls_per_day": 1000,
    "bookings_per_month": 500
  },
  "usage": {
    "api_calls_today": 153,
    "api_calls_remaining_daily": 847,
    "bookings_this_month": 87,
    "bookings_remaining_monthly": 413
  },
  "reset_at": {
    "daily": "2026-02-18T00:00:00.000Z",
    "monthly": "2026-03-01T00:00:00.000Z"
  }
}

Upgrading Your Limits

If you're consistently hitting rate limits, consider upgrading your plan. Visit the pricing page for details, or use the Stripe billing portal to manage your subscription.