> ## Documentation Index
> Fetch the complete documentation index at: https://docs.predictiondata.dev/llms.txt
> Use this file to discover all available pages before exploring further.

# Common problems

> Troubleshooting downloads, auth, and API responses

Here are frequent issues and how to fix them. If something isn’t covered, email [calder@predictiondata.dev](mailto:calder@predictiondata.dev).

## Download returns 404 or “file not found”

**Polymarket**

* **Check the date.** Exports are generated daily. Use a date that exists in the list response. Polymarket uses the v1 API, which does **not** zero-pad months and days (e.g. `2025-11-8`, not `2025-11-08`). Kalshi uses the v2 API, which uses standard `YYYY-MM-DD` formatting.
* **Check the path.** For asset ID: `https://datasets.predictiondata.dev/polymarket/{export_type}/{asset_id}/{date}.csv.gz` — use `books`, `trades`, or `onchain/fills` as the export type (not plain `onchain`). For slug: `https://datasets.predictiondata.dev/polymarket/{export_type}/{market_slug}/{outcome}/{date}.csv.gz?slug=true&apikey=YOUR_KEY` (e.g. `.../books/will-the-seattle-seahawks-win-super-bowl-2026/YES/2026-2-9.csv.gz?slug=true&apikey=...`).
* **List first.** Call the [list endpoint](/datasets/polymarket/available-files) and use the same `asset_id` and `date` (or slug/outcome) that appear there. Don’t guess IDs or dates.

**Kalshi**

* Use the **exact `path`** from the list response in `GET /v2/datasets/{path}`. Don’t modify or construct the path yourself.
* The download URL returns a **302 redirect**. If your client doesn’t follow redirects, you’ll get a redirect response instead of the file. Use `curl -L` or enable redirect following in your HTTP client.

## “Unauthorized” or authentication errors

* **Polymarket downloads:** Auth is via the **query parameter** `apikey=YOUR_API_KEY`. If you forget it or typo the key, you’ll get 401/403.
* **Kalshi:** Auth is the **header** `x-auth-token: YOUR_API_KEY`. Query params are not used for auth. Make sure the header is sent on both the list and the download request.
* **Wrong tier:** Your key’s tier must allow the exchange (e.g. Kalshi tier for Kalshi data). If you get access denied, ask [calder@predictiondata.dev](mailto:calder@predictiondata.dev) to confirm your tier.

## List returns empty or no exports

* **Polymarket:** Confirm the market/event/asset exists and has data for the date range. New markets may not have backfilled history yet. Try an event slug you know has markets (e.g. from the Polymarket site).
* **Kalshi:** Same idea — check the ticker. Ensure you’re sending `x-auth-token`; missing or invalid tokens return a 401 error.
* **Date:** Exports are usually produced once per day. There is no same-day data for “today” until the next run (e.g. after 2am UTC for Polymarket).

## Wrong or weird date format

* **Polymarket (v1 API):** Dates are **not** zero-padded (e.g. `2025-11-8`, not `2025-11-08`). Use the exact date string from the list response.
* **Kalshi (v2 API):** Standard `YYYY-MM-DD` format (e.g. `2025-11-08`).
* All times are **UTC**. The “day” of an export is the UTC date.

## Slug vs asset ID (Polymarket) — which to use?

* **Event slug** — What you see in the URL for a Polymarket *event* (e.g. `super-bowl-champion-2026-731`). Use it to list all markets in that event.
* **Market slug** — The URL-friendly name for a single *market* (e.g. `will-the-seattle-seahawks-win-super-bowl-2026`).
* **Asset ID** — The internal CLOB token ID (long number). You get it from our list response. Use it in download URLs when you don’t want to pass slug + outcome.

For **downloading**, you can either:

* Use `asset_id` + `date` in the path and `apikey` in the query, or
* Use `market_slug` + `outcome` (YES/NO) + `date` in the path and **both** `slug=true` and `apikey` in the query. Don’t mix: if you use slug in the path, you must set `slug=true`.

## Kalshi download returns HTML or a redirect URL instead of the file

The Kalshi download endpoint returns a **302 redirect** to a signed CloudFront URL. You must **follow that redirect** to get the file. In curl, use `-L`. In code, allow your HTTP client to follow redirects (often the default). If you only read the first response body, you’ll get the redirect page or URL, not the actual data.

## Rate limits / “too many requests”

We do **not** rate limit by request count or download volume for normal use. If you see rate-limiting errors, they may be from a proxy or from the CDN (e.g. after following the Kalshi redirect). If you’re doing very high volume (e.g. bulk backfill), reach out to [calder@predictiondata.dev](mailto:calder@predictiondata.dev).

## How do I read the files?

**CSV files** are gzip-compressed (`.csv.gz`):

* **Command line:** `gunzip -k file.csv.gz` or `gzip -dc file.csv.gz > file.csv`.
* **Python:** `pandas.read_csv('file.csv.gz')` (pandas handles gzip automatically).
* **Other languages:** Use a gzip library or decompress before parsing.

**Parquet files** (`.parquet`, Kalshi only) are zstd-compressed:

* **Python:** `pandas.read_parquet('file.parquet')` or use `pyarrow`.
* **Other languages:** Use any Parquet library (Arrow, DuckDB, etc.).

## Still stuck?

* Double-check the [Quickstart](/quickstart) for the exact URLs and parameters.
* Confirm your API key and tier with [calder@predictiondata.dev](mailto:calder@predictiondata.dev).
* For Polymarket, re-fetch the list response and use the same `asset_id`, `date`, and `export_type` (or slug + outcome) in your download URL.
* For Kalshi, re-fetch the list response and use the exact `path` from the response.