Rate Limits

Docs pages

All CardAPI requests are rate-limited per account on a daily and monthly basis: every API key on your account shares one quota, and calls made with a key you have since revoked still count until the window resets. Limits reset at midnight UTC for the daily window and on the 1st of each calendar month for the monthly window.

Limits by Plan

Plan	Daily	Monthly
Free	100 calls / day	3,000 calls / month
Starter	500 calls / day	15,000 calls / month
ProPopular	2,000 calls / day	50,000 calls / month
Enterprise	20,000 calls / day	500,000 calls / month

Get a free API key, compare plans on the pricing page, or upgrade an existing key in the developer portal.

Response Headers

Every API response includes the following headers so you can track your usage programmatically.

X-RateLimit-Limit100

Your plan's daily call limit.

X-RateLimit-Remaining57

Calls remaining in the current day window (the smaller of your daily and monthly remaining).

X-RateLimit-Reset1743465600

Unix timestamp (UTC) when the daily window resets (midnight UTC).

X-RateLimit-Limit-Monthly3000

Your plan's monthly call limit.

X-RateLimit-Remaining-Monthly2481

Calls remaining in the current calendar month.

X-RateLimit-Reset-Monthly1746057600

Unix timestamp (UTC) when the monthly window resets (start of next month, UTC).

Retry-After3600

Present on a 429 or 503 response. On a 429, seconds until you can retry -- accounts for whichever limit (daily or monthly) is actually blocking you. On a 503, 30: retry shortly.

When You Hit the Limit

Once your daily or monthly quota is exhausted, the API returns 429 Too Many Requests with a JSON error body:

HTTP/1.1 429 Too Many Requests
X-CardAPI-Plan: free
X-RateLimit-Limit: 100
X-RateLimit-Remaining: 0
X-RateLimit-Reset: 1743465600
X-RateLimit-Limit-Monthly: 3000
X-RateLimit-Remaining-Monthly: 2900
X-RateLimit-Reset-Monthly: 1746057600
Retry-After: 3600

{
  "error": {
    "code": "rate_limited",
    "message": "Daily limit of 100 calls reached on the Free plan. Starter gives 500 calls/day and 15,000/month, with a 7-day free trial for new customers: https://cardapi.dev/pricing",
    "plan": "free",
    "limit": "daily",
    "limit_value": 100,
    "upgrade_url": "https://cardapi.dev/pricing?utm_source=api&utm_medium=error&utm_campaign=rate_limited",
    "docs_url": "https://cardapi.dev/docs/rate-limits"
  }
}

plan is your plan, limit is the window that blocked the call (daily or monthly; monthly when both are used up) and limit_value its size. upgrade_url points at the next plan (on Enterprise, at the contact page) and docs_url at this page. code stays rate_limited, so match on it, not on the message.

Your client should inspect X-RateLimit-Remaining proactively and back off before hitting zero, rather than relying on 429 responses to throttle.

If CardAPI briefly can't check your usage, it answers 503 service_unavailable with Retry-After: 30. That is not your quota: retry after 30 seconds.

Check Your Usage

You can query your current usage at any time via the GET /v1/auth/usage endpoint:

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

{
  "tier": "free",
  "daily_used": 42,
  "daily_limit": 100,
  "monthly_used": 310,
  "monthly_limit": 3000
}

This call counts toward your quota like any other. The X-RateLimit-* headers on every response carry the same numbers, so you rarely need to call it.

Best Practices

Cache responses on your end
Card data changes infrequently: issuer sites are scheduled to be re-checked once a week, and GET /v1/stats returns last_updated, the time card data last changed. Cache responses for at least an hour to avoid redundant calls. Cached data may be kept only while your plan is active, per the Terms of Service.
Use webhooks for change notifications
Enterprise customers can subscribe to card.created, card.updated and card.deleted events instead of polling, and re-fetch only the cards that changed.
Batch requests where possible
Use the /v1/cards/compare endpoint to fetch multiple cards in a single request rather than calling /v1/cards/:slug repeatedly.
Monitor X-RateLimit-Remaining
Read the rate limit headers on every response. If Remaining drops below 10% of your limit, slow your request rate to avoid hitting the cap.
Upgrade before you hit limits
If you regularly approach your daily limit, upgrade your plan. Upgrade takes effect immediately and the higher limits apply to your next request.

← API Reference Get a free API key →