Errors and limits

Status codes, plan restrictions, and how to handle 429s.

Error bodies are JSON with a detail string. Validation errors (422) use an array of field errors instead.

{ "detail": "Invalid or expired API key." }

Status codes

Status	When it happens
400	Bad timestamp, date range, limit, or cursor
401	Missing, invalid, or expired API key
403	Plan does not allow this data point, resolution, or lookback
404	Market or token not found
422	Parameter failed schema validation
429	Requests-per-minute limit exceeded
500	Unexpected server error

Plan limits

Plans gate three things:

• Finest resolution (1m through 1d)
• Rolling lookback window (max_history_days)
• Which of metrics, prices, and books you can query

GET /v1/usage returns the live values for your key:

{
  "plan": "trader",
  "organization": "Acme Corp",
  "limits": {
    "requests_per_minute": 100,
    "requests_remaining": 95,
    "granularity_allowed": "1m",
    "max_history_days": 30,
    "data_points": {
      "metrics": true,
      "prices": true,
      "books": true
    }
  },
  "reset_at": 1706184000
}

A history call outside those limits returns 403, for example:

{ "detail": "Your plan does not allow historical order books." }

Compare your request to GET /v1/usage before you retry. Upgrading a plan takes effect immediately.

Rate limits

429 means you exhausted the current RPM window. reset_at on /v1/usage is the Unix timestamp when the window resets (null on unlimited plans).

{ "detail": "Rate limit exceeded. Please try again later." }

Reuse a requests.Session (or the SDK client) and pace bursts. A short sleep between market loops is faster end-to-end than retrying 429s.

The Python SDK retries 429 and 5xx with exponential backoff and jitter. Tune max_retries, retry_backoff_base, retry_backoff_max, and timeout on PolymarketDataClient.

History validation examples

Problem	Typical detail
limit above 200	limit too large. Requested: 250, Maximum: 200
Market-level page too small	limit too small for this market. Minimum required: 3
Too many tokens	Market has more than 200 tokens. Use /v1/tokens/{token_id}/prices instead.
Bad resolution	Input should be '1m', '10m', '1h', '6h' or '1d'

Standard coverage starts in August 2025. Asking for an earlier start_ts on a non-enterprise plan returns 403.