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

# Troubleshooting

> Common issues and solutions

Quick fixes for frequent problems with Probalytics.

## Authentication Issues

### "Invalid API credentials" (401)

**Cause:** Incorrect authorization header format.

**Fix:** Ensure the format is `Bearer API_KEY_ID:API_KEY_SECRET`:

```bash theme={null}
# Wrong
curl -H "Authorization: api_xxx:sk_xxx" ...
curl -H "Authorization: Bearer api_xxx" ...

# Correct
curl -H "Authorization: Bearer api_xxx:sk_xxx" ...
```

### "Access denied" (403)

**Cause:** Your plan doesn't have access to the requested data.

**Common scenarios:**

* Starter tier requesting data older than 30 days
* Querying `orderbook_snapshots` table without Early Access

**Fix:** Upgrade your plan or adjust your query to stay within tier limits.

***

## SQL / ClickHouse Issues

### "Authentication failed"

**Cause:** Wrong username/password or connection settings.

**Checklist:**

* Host: `clickhouse.probalytics.io`
* Port: `9440` (Secure TCP) or `8443` (Secure HTTPS)
* Database: `probalytics`
* Username and password from dashboard (not API keys)
* TLS/SSL enabled (use `--secure` flag for CLI)

### Query Times Out

**Cause:** Query is too broad or inefficient.

**Fix:** Add filters on ORDER BY columns:

```sql theme={null}
-- Slow: No filters
SELECT * FROM fills WHERE price > 0.9;

-- Fast: Filter by ORDER BY columns first
SELECT * FROM fills
WHERE platform = 'POLYMARKET'
  AND market_id = 'your-market-uuid-here'
  AND timestamp >= now() - INTERVAL 7 DAY
  AND price > 0.9;
```

See [SQL Tips](/docs/sql-guide/tips) for optimization guidance.

### "Max rows exceeded" or Truncated Results

**Cause:** Starter tier has a 100,000 row limit.

**Fix:**

* Add `LIMIT` to your query
* Use aggregations (`count()`, `sum()`, `avg()`) instead of raw rows
* Narrow your date range
* Upgrade to Pro for 1 billion row limit

### "Memory limit exceeded"

**Cause:** Query uses too much memory.

**Fixes:**

* Add stricter filters to reduce data scanned
* Use `SAMPLE` for approximate results:
  ```sql theme={null}
  SELECT avg(normalized_price) FROM fills SAMPLE 0.1 WHERE ...
  ```
* Break query into smaller date ranges
* Upgrade tier for higher memory limits

### Duplicate Rows in Results

**Cause:** `ReplacingMergeTree` hasn't merged yet.

**Fix:** Add `FINAL` for exact results (slower):

```sql theme={null}
SELECT count() FROM markets FINAL;
```

For most analytics, duplicates are negligible—skip `FINAL` for speed.

***

## REST API Issues

### Rate Limited

**Cause:** Exceeded rate limit of 3,000 requests per 10 seconds.

**Fix:**

* Reduce request frequency and batch where possible
* Cache responses where possible
* The database may saturate before the hard limit under heavy parallel load — stay well below the ceiling

<Note>
  SQL/ClickHouse connections have separate per-tier query limits (Starter: 100/hour, Pro: 1,000/hour, Custom: unlimited). If your SQL queries are being throttled, check your tier in the dashboard.
</Note>

### Empty Results

**Cause:** Filters too restrictive or wrong format.

**Checklist:**

* Dates must be RFC3339: `2024-01-01T00:00:00Z`
* Enum values are uppercase: `POLYMARKET`, `ACTIVE`, `BUY`
* UUIDs must be valid format

### Slow Response Times

**Cause:** Requesting too much data at once.

**Fixes:**

* Use cursor-based pagination with `limit` and `cursor` parameters
* Add filters: `platform`, `start_time`, `end_time`, `market_id`
* Request only active/recent data

***

## Data Issues

### Missing Recent Data

**Cause:** Indexing delay (typically \< 5 minutes).

**Note:** Data is indexed from blockchain events and platform APIs. During high activity, there may be brief delays.

### Price Shows 0 or Null

**Cause:** Some fills (especially older ones) may have incomplete data.

**Fix:** Filter for valid data:

```sql theme={null}
WHERE normalized_price > 0 AND normalized_price <= 1
```

### Market Not Found

**Cause:** Market may be:

* Too new (not indexed yet)
* From an unsupported platform
* Using wrong ID format

**Tip:** Use `platform_id` for platform-native IDs, `id` for Probalytics UUIDs.

***

## Connection Issues

### Can't Connect to ClickHouse

**Checklist:**

1. Firewall allows outbound port 9440 (Secure TCP) or 8443 (Secure HTTPS)
2. Using correct host: `clickhouse.probalytics.io`
3. Credentials are for ClickHouse (not API keys)
4. TLS/SSL is enabled in your client (use `--secure` flag for CLI)
5. Try HTTPS port (8443) if TCP (9440) is blocked

### SSL/TLS Errors

**Fix:** All connections require TLS. Ensure your client is configured for secure connections:

```bash theme={null}
# CLI - use --secure flag
clickhouse client --host=clickhouse.probalytics.io --secure --port=9440 --user=YOUR_USERNAME --password=YOUR_PASSWORD --database=probalytics
```

```python theme={null}
# clickhouse-driver - use secure=True and port 9440
client = Client(host='clickhouse.probalytics.io', port=9440, secure=True, ...)

# clickhouse-connect - use port 8443 (HTTPS)
client = clickhouse_connect.get_client(host='clickhouse.probalytics.io', port=8443, ...)
```

***

## Still Stuck?

If none of these solutions work:

1. Check [Discord](https://discord.gg/probalytics) for similar issues
2. Contact [support](/docs/support) with:
   * Error message (full text)
   * Query or code
   * Timestamp
   * Your tier