Tiers & rate limits
Tiers
There are three tiers. The response shape is identical at every tier — the
key set never changes; values your tier can't see are simply null. So you can
write one parser and read tier from the data, not from which keys exist.
| Capability | Free | Hobby | Pro |
|---|---|---|---|
| Sets, cards, Pokémon, search (metadata) | ✓ | ✓ | ✓ |
| Image URL fields (public CDN, fetchable by anyone) | ✓ | ✓ | ✓ |
Variant cards (in listings, search & /cards/{id}/variants) | — | ✓ | ✓ |
prices on card detail & /cards/{id}/prices | null / 403 | raw only | all grades |
Sort by price_raw, has_price filter | 400 | ✓ | ✓ |
Sort by price_psa10 | 400 | 400 | ✓ |
/cards/{id}/sales | 403 | 403 | ✓ |
Notes:
- Free sees metadata for base/standalone cards only. Variant cards are
hidden from listings and search, fetching one by id returns
403 tier_required, and/cards/{id}/variantsis403. No pricing anywhere (pricesisnull). - Hobby adds variant cards and raw prices. The six graded entries in
prices.gradesare present butnull. - Pro adds all graded prices (PSA 8/9/10 and other 8/9/10) and the sales endpoint.
Image URLs are not a tier perk — image_url (cards) and pack_image_url
(sets) are returned to all tiers and point at our public CDN
(images.pikaqian.com), fetchable without a key.
Rate limits
Two independent limits apply to authenticated requests:
| Limit | Free | Hobby | Pro |
|---|---|---|---|
| Burst (requests / minute) | 60 | 300 | 1,200 |
| Monthly quota (requests / billing cycle) | 500 | 5,000 | 50,000 |
Exceeding either returns 429 rate_limited with a Retry-After header (seconds
until the exceeded window reopens).
Rate-limit headers
Every authenticated response advertises your current limit state so you can self-throttle without parsing 429s:
| Header | Meaning |
|---|---|
X-RateLimit-Limit | Per-minute burst ceiling for your tier. |
X-RateLimit-Remaining | Burst requests left in the current minute. |
X-RateLimit-Reset | Unix epoch when the burst window resets. |
X-RateLimit-Quota | Monthly request quota for your tier. |
X-RateLimit-Quota-Remaining | Quota left in the current billing cycle. |
X-RateLimit-Quota-Reset | Unix epoch when the billing cycle (and quota) resets. |
On a 429, Remaining (or Quota-Remaining) is 0 and Retry-After is set.
Watch X-RateLimit-Remaining and back off before you hit zero. If you do get a
429, wait the number of seconds in Retry-After before retrying — ideally
with exponential backoff and jitter.