The Prediction Markets
Concepts

Errors

Errors use normal HTTP status codes and one JSON shape with a stable, dotted code. Branch on code, not on message: messages may be reworded.

Error shape

404 response
{
  "error": {
    "code": "not_found.event",
    "message": "Event not found",
    "request_id": "0f8969a6-0968-4d7c-9cbb-de379e8c19c4"
  }
}
FieldDescription
error.codeStable, dotted code from the table below. New codes may be added.
error.messageA human-readable explanation. For validation errors it names the parameter.
error.request_idSame as the X-Request-ID header. Quote it to support.

All error codes

HTTPCodeMeaningWhat to do
401auth.missing_keyNo X-API-Key header.Add the header. See authentication.
401auth.invalid_keyThe key is unknown or revoked.Check for typos, or create a new key at API keys.
429rate_limit.per_secondToo many requests this second.Wait Retry-After seconds, then retry.
429rate_limit.monthly_quotaYour monthly quota is used up.Retry-After is the seconds until the quota resets (start of next month, UTC).
400validation.invalid_parameterA parameter has the wrong type or is out of range, or a required one is missing.Fix the parameter named in message, e.g. limit: Input should be less than or equal to 200.
400validation.invalid_cursorThe cursor is malformed or was made with other filters.Restart from the first page without cursor.
400validation.missing_parameter/matches got neither url nor venue and id.Send one of the two.
400validation.invalid_urlThe url is not a Kalshi or Polymarket link.Send a kalshi.com or polymarket.com link.
400validation.invalid_idA /prices id is not a venue:contract_id pair.Use e.g. kalshi:KXPRESNOMD-28-GN.
400validation.too_many_idsMore than 100 ids in one /prices call.Split into batches of 100.
404not_found.eventNo event with that slug.Search with /events.
404not_found.marketNo venue market with that id, or TPM does not track it yet.Check the venue and id with /markets.
503upstream.unavailableA service TPM depends on is briefly unavailable.Retry with exponential backoff.

Retry safely

  • Retry 429 after the Retry-After header (seconds).
  • Retry 503 and network errors with exponential backoff: 1 s, 2 s, 4 s, up to about a minute.
  • Do not retry other 4xx errors unchanged; fix the request first.
Retry helper
import os
import time

import requests

BASE = "https://api.thepredictionmarkets.com/api/public/v1"
HEADERS = {"X-API-Key": os.environ["TPM_API_KEY"]}


def get(path, params=None, attempts=5):
    delay = 1
    for _ in range(attempts):
        resp = requests.get(BASE + path, params=params, headers=HEADERS, timeout=20)
        if resp.status_code == 429:
            time.sleep(int(resp.headers.get("Retry-After", "1")))
            continue
        if resp.status_code >= 500:
            time.sleep(delay)
            delay = min(delay * 2, 60)
            continue
        body = resp.json()
        if not resp.ok:
            err = body["error"]
            raise RuntimeError(f"{err['code']} ({err['request_id']}): {err['message']}")
        return body
    raise RuntimeError("gave up after retries")

Related

Build with TPM

Get your free API key

One key gives you Kalshi and Polymarket events, prices with freshness, price history, cross-venue gaps and the live quotes WebSocket.

Get a free API keyRead the quickstart