Polymarket API Error Handling

The PolyOrderbooks API uses conventional HTTP status codes. Error bodies fall into two shapes depending on the layer that rejected the request.

Response shapes

Gateway auth (`401`)

Authentication and rate-limit responses use a single detail field:

{
  "detail": "Authentication required."
}

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

Application errors (`400`, `403`, `404`)

Business logic and validation use error + message:

{
  "error": "bad_request",
  "message": "start_ts is required"
}

Rate limits (`429`)

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

Includes Retry-After header (seconds). See Rate limits.

Status code reference

Code	Meaning	Typical body	Action
`400`	Invalid parameters	`error` + `message`	Fix request; do not retry unchanged
`401`	Missing/invalid API key	`detail`	Check `X-API-Key` header
`403`	Plan limit or permission	`error` + `message`	Upgrade plan or adjust query
`404`	Resource not found	`error` + `message`	Verify slug, token id, or filters
`429`	Rate limit exceeded	`detail`	Wait for `Retry-After`, then retry
`500`	Server error	varies	Retry with exponential backoff

Common validation errors

Missing parameters
Invalid time window
Unsupported resolution
Not found

{
  "error": "bad_request",
  "message": "start_ts is required"
}

{
  "error": "bad_request",
  "message": "end_ts must be after start_ts"
}

{
  "error": "bad_request",
  "message": "Unsupported resolution '2m'. Allowed: 10m, 15m, 1d, 1h, 1m, 1s, 5m, 60s, 6h"
}

{
  "error": "not_found",
  "message": "Market not found: unknown-slug"
}

Integration pattern

import requests

response = requests.get(url, params=params, headers=headers, timeout=60)

if response.status_code == 429:
    retry_after = int(response.headers.get("Retry-After", 60))
    # time.sleep(retry_after) and retry — see rate-limits.mdx

if not response.ok:
    try:
        payload = response.json()
        msg = payload.get("message") or payload.get("detail") or response.text
    except Exception:
        msg = response.text
    raise RuntimeError(f"API error {response.status_code}: {msg}")

payload = response.json()

Log HTTP status, request path, and the parsed error string. Include your client request id when contacting contact@polyorderbooks.com.

Idempotency

GET requests are safe to retry on transient network failures and 5xx responses. Do not retry 400, 403, or 404 without changing the request. Related reading: Polymarket API guide covers retry patterns against both the official API and this archive.

Getting started

Discovery

Historical

Backtest AI

Reference

Polymarket API Error Handling

Response shapes

Gateway auth (`401`)

Application errors (`400`, `403`, `404`)

Rate limits (`429`)

Status code reference

Common validation errors

Integration pattern

Idempotency

​Response shapes

​Gateway auth (401)

​Application errors (400, 403, 404)

​Rate limits (429)

​Status code reference

​Common validation errors

​Integration pattern

​Idempotency

Response shapes

Gateway auth (`401`)

Application errors (`400`, `403`, `404`)

Rate limits (`429`)

Status code reference

Common validation errors

Integration pattern

Idempotency