Error Codes

The API uses standard HTTP status codes and returns consistent JSON error responses. All errors include an error field with a human-readable message, and may include additional context like rate limit info or upgrade URLs.

Code	Name	Description
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

Response Examples

400Bad Request

Invalid request parameters or malformed request body

Invalid limit parameter

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

Invalid cursor

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

401Unauthorized

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"
}

403Forbidden

Access denied or upgrade required for the requested resource

Graded data requires Pro plan

{
  "error": "Pro plan required",
  "message": "Graded card prices (PSA, BGS, CGC) require a Pro plan.",
  "code": "UPGRADE_REQUIRED",
  "upgradeUrl": "https://poketrace.com/dashboard/plan"
}

EU market requires Pro plan

{
  "error": "Pro plan required",
  "message": "EU market (Cardmarket) data requires a Pro plan.",
  "code": "UPGRADE_REQUIRED",
  "upgradeUrl": "https://poketrace.com/dashboard/plan"
}

WebSocket access denied

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

404Not 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'"
}

429Rate Limited

Too many requests - burst or daily limit exceeded

Burst rate limit exceeded (30 req/10s per API key)

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

Daily limit exceeded

{
  "error": "Daily rate limit exceeded. Resets at 2026-01-18T00:00:00Z",
  "usage": {
    "plan": "Free",
    "daily": {
      "remaining": 0,
      "limit": 250,
      "resetsAt": "2026-01-18T00:00:00Z"
    }
  }
}

500Internal 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 your usage:

X-RateLimit-LimitYour plan's daily request limit

X-RateLimit-RemainingDaily requests remaining

X-RateLimit-ResetISO8601 timestamp when daily limit resets

Retry-AfterSeconds until retry (429 responses only)

X-PlanYour current plan (Free, Pro, Scale)