What counts
Every request admitted through the per-minute limit counts once toward the billing-period quota, including a Redis cache hit and an application-level error produced after authentication. Authentication failures and requests rejected by the per-minute limiter do not consume the billing-period quota.
For Free starter, admitted requests consume the one-time allowance until its granted requests are used. Cache hits and later application-level errors count; authentication failures, per-minute rejections, and requests rejected because the free allowance is already exhausted do not consume another free request. All keys share the same total; rotating or revoking a key does not restore requests.
The 200-request free allowance is granted only to new accounts while the offer is enabled, at 30 requests per minute. It requires no card and has no expiry, renewal, or automatic reset. Existing accounts keep their granted allowance and usage; older accounts without a grant are not backfilled.
Provider refresh traffic is internal ingestion work and is never billed to a customer.
Response headers
| Header | Meaning |
|---|---|
| X-RateLimit-Limit | Maximum requests in the current minute. |
| X-RateLimit-Remaining | Requests left in that minute. |
| X-RateLimit-Reset | Unix timestamp for the next minute window. |
| X-Quota-Limit | Maximum requests in the current billing period, or the stored one-time free allowance (200 for new grants; existing grants are retained). |
| X-Quota-Remaining | Requests left in the billing period or one-time free allowance, shared across all account keys. |
| X-Quota-Reset | Unix timestamp when a paid billing-period counter resets. The value 0 means the one-time free allowance has no scheduled reset; it is not a retry timestamp. |
| Retry-After | Seconds until the applicable reset for rate_limit or monthly_quota errors. Omitted for free_allowance_exhausted because there is no reset to wait for. |
| X-StatsAPI-Cache | HIT or MISS for the versioned response cache. |
Handle HTTP 429
Stop sending requests when a 429 response arrives. Retry after the next minute boundary for a rate-limit error; a depleted monthly quota requires the billing period to reset or the account plan to change.
For rate_limit and monthly_quota errors, use Retry-After for delay duration and the matching X-RateLimit-Reset or X-Quota-Reset timestamp for scheduling. Add jitter for unexpected bursts and cache stable responses in your own application when appropriate.
For free_allowance_exhausted, stop automatic retries and choose a paid plan. This HTTP 429 response has X-Quota-Reset: 0, details.reset_at: null, details.upgrade_url pointing at the plans, and no Retry-After header. Waiting for a new month or creating a new key does not replenish the account-wide allowance.