Rate Limits

The CardMind API enforces per-minute and monthly quotas to ensure fair access. Limits are tracked per API key using a sliding window and are returned as response headers on every request.

Limits by Tier

Limits apply to Bearer token requests only. Internal fleet callers (using X-Internal-Secret) are always unlimited.

Tier	Per Minute	Per Month	Premium endpoints
Internal	Unlimited	Unlimited	✓ Included
Free	10 / min	1,000 / mo	✗ Not available
Premium	60 / min	Unlimited	✓ Included

Monthly quotas reset at the start of each calendar month (UTC midnight, first of the month). The per-minute window uses a sliding window — not a fixed clock minute.

Rate Limit Headers

Every successful API response includes these headers so you can track your remaining quota and implement backoff logic without waiting for a 429.

Header	Type	Description
X-RateLimit-Limit	integer	The binding limit — whichever quota is currently most restrictive (per-minute or monthly)
X-RateLimit-Remaining	integer	Calls remaining before the binding limit is hit
X-RateLimit-Reset	Unix timestamp (s)	When the current window resets — a Unix timestamp in seconds (UTC)

Example response headers

HTTP/2 200 OK
Content-Type: application/json
X-RateLimit-Limit: 10
X-RateLimit-Remaining: 7
X-RateLimit-Reset: 1745000060

In this example, a free-tier key has used 3 of its 10 per-minute calls. The window resets at Unix timestamp 1745000060.

Handling 429 Rate Limited

When your quota is exceeded the API returns HTTP 429 with a RATE_LIMITED error code. The rate limit headers are included on 429 responses — use X-RateLimit-Reset to determine when to retry.

429 response body

{
  "data": null,
  "error": {
    "message": "Rate limit exceeded",
    "code": "RATE_LIMITED"
  }
}

Recommended retry pattern (JavaScript)

const res = await fetch('https://api.cardmind.app/api/cards/search?q=bolt', {
  headers: { Authorization: 'Bearer cm_live_YOUR_KEY' },
})

if (res.status === 429) {
  const resetAt = Number(res.headers.get('X-RateLimit-Reset')) * 1000
  const waitMs = Math.max(resetAt - Date.now(), 1000)
  await new Promise(r => setTimeout(r, waitMs))
  // retry request...
}

Quota Notes

Each request counts toward your monthly quota regardless of the HTTP response status.
The per-minute limit uses a sliding 60-second window, not a fixed clock-aligned minute.
Monthly quotas reset at UTC midnight on the first of each calendar month.
Premium endpoints (/api/collection/value, /api/webhooks, /api/ai/analyze) return 403 PREMIUM_REQUIRED for free-tier keys — these do not consume quota.
Upgrading to Premium takes effect immediately — no key regeneration needed.

Need Higher Limits?

Upgrade to CardMind Premium for 60 requests per minute, unlimited monthly calls, and access to premium endpoints including AI card analysis, collection valuation, and webhooks.