Quotas & rate limits

Two separate limits apply, and they are not the same thing.

Rate limit — how fast

A per-minute ceiling on requests, sized to your plan. Exceeding it returns 429 rate_limited with a Retry-After header. This protects shared infrastructure; it is not a billing control.

Credit quota — how much

A hard monthly ceiling on credits. Exceeding it returns 402 quota_exceeded.

The quota is counted in credits, not calls. A six-credit matching call consumes six units of quota. A 50,000-credit plan therefore buys 50,000 daily horoscopes, or about 8,300 compatibility matches, or any mix in between.

The quota fails closed

At the ceiling we stop serving rather than continue and bill you for the overage. You will never receive an invoice you did not authorise. If a call would take you past the ceiling, it is rejected before it runs — so a single expensive call cannot straddle the boundary.

Watching your position

Every response carries the current state:

X-RateLimit-Limit: 120
X-Quota-Limit: 50000
X-Quota-Remaining: 31480
X-Credits-Charged: 6.0

Alert on X-Quota-Remaining in your own monitoring. Do not wait for the first 402 to find out you are close.

Raising a limit

Top-ups apply immediately. Contact us and the new ceiling is live within minutes — no redeploy on your side.