Reference

Errors

The API uses standard HTTP status codes and returns consistent JSON errors. Every error has an error field with a readable message, and some include extra context such as an error code or rate limit info.

Status codes

Code	Name	Meaning
200	OK	Request successful
400	Bad Request	Invalid request parameters or malformed request body
401	Unauthorized	Missing or invalid API key
403	Forbidden	Access denied or upgrade required for the requested resource
404	Not Found	The requested resource could not be found
429	Rate Limited	Too many requests - burst or daily limit exceeded
500	Internal Server Error	An unexpected error occurred on the server

400 Bad Request

Invalid request parameters or malformed request body.

Invalid limit parameter

{
  "error": "Invalid limit parameter",
  "message": "Limit must be a number between 1 and 20"
}

Invalid cursor

{
  "error": "Invalid cursor",
  "message": "The provided cursor is malformed or expired"
}

401 Unauthorized

Missing or invalid API key.

Missing API key

{
  "error": "API key required",
  "message": "Include your API key in the X-API-Key header"
}

Invalid API key

{
  "error": "Invalid API key",
  "message": "The provided API key is not valid"
}

Inactive API key

{
  "error": "API key is inactive",
  "message": "This API key has been deactivated"
}

403 Forbidden

Access denied or upgrade required for the requested resource.

Graded data requires Pro plan

{
  "error": "Graded card data requires a Pro plan",
  "code": "UPGRADE_REQUIRED"
}

EU market requires Pro plan

{
  "error": "EU market data requires a Pro plan",
  "code": "UPGRADE_REQUIRED"
}

Price history beyond 7 days requires Pro or higher (Free plan, v2)

{
  "error": "Price history beyond 7 days (period=30d, 90d or 1y) requires Pro or higher",
  "code": "UPGRADE_REQUIRED"
}

Price history period=all requires Scale or Business (v2)

{
  "error": "Full price history (period=all) requires Scale or Business",
  "code": "UPGRADE_REQUIRED"
}

WebSocket access denied

{
  "error": "Scale or Business plan required",
  "message": "WebSocket connections require a Scale or Business plan.",
  "code": "UPGRADE_REQUIRED"
}

404 Not Found

The requested resource could not be found.

Card not found

{
  "error": "Card not found",
  "message": "No card exists with the ID 'invalid_id'"
}

Set not found

{
  "error": "Set not found",
  "message": "No set exists with the slug 'invalid-set'"
}

429 Rate Limited

Too many requests - burst or daily limit exceeded.

Burst rate limit exceeded (plan-based: Free 1/2s, Pro 30/10s, Growth 45/10s, Scale 60/10s, Business 300/10s)

{
  "error": "Too many requests. Slow down.",
  "code": "BURST_RATE_LIMIT_EXCEEDED",
  "retryAfter": 7
}

Daily limit exceeded (Free plan on /v2)

{
  "error": "Daily rate limit exceeded (100 requests per day on /v2 for the Free plan). Resets at 2026-01-18T00:00:00Z",
  "usage": {
    "plan": "Free",
    "daily": {
      "remaining": 0,
      "limit": 100,
      "resetsAt": "2026-01-18T00:00:00Z"
    }
  }
}

500 Internal Server Error

An unexpected error occurred on the server.

{
  "error": "Internal server error",
  "message": "An unexpected error occurred. Please try again later.",
  "requestId": "req_a1b2c3d4e5f6"
}

Rate limit headers

All authenticated responses include rate limit headers to help you track usage.

Header	Description
`X-RateLimit-Limit`	Your plan's daily request limit
`X-RateLimit-Remaining`	Daily requests remaining
`X-RateLimit-Reset`	ISO8601 timestamp when the daily limit resets
`Retry-After`	Seconds until you can retry (429 responses only)
`X-Plan`	Your current plan (Free, Pro, Growth, Scale, Business)