> ## 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.

# Errors & Request Behavior

> REST API errors, validation, and retry behavior

The REST API uses PocketBase-style JSON errors. An error response includes the HTTP status in both the response status code and the `status` field.

## Error response format

```json theme={null}
{
  "data": {},
  "message": "Human-readable error description.",
  "status": 400
}
```

| Field | Type | Description |
| - | - | - |
| `status` | `integer` | HTTP status code |
| `message` | `string` | Human-readable summary; capitalization and exact wording can vary |
| `data` | `object` | Additional details; empty when no structured details are available |

Validation details are keyed by request field and contain their own `code` and `message` values:

```json theme={null}
{
  "data": {
    "start_time": {
      "code": "validation_invalid_date",
      "message": "Invalid date format."
    }
  },
  "message": "Invalid params.",
  "status": 400
}
```

Do not build program logic around the exact English wording. Use the HTTP status and structured validation keys where present.

## HTTP status codes

### 400 Bad Request

Returned when a validated parameter is outside its accepted values, including:

* dates that are not RFC 3339, such as `2026-03-01` without a time and timezone;
* unsupported `platform`, `status`, or `taker_side` values;
* numeric limits below 1 or above 1,000.

Some malformed values are currently handled more permissively:

* a nonnumeric `limit` falls back to the default value of 100;
* a malformed pagination `cursor` is ignored and the first page is returned;
* `market_id` is passed to the database without route-level UUID validation.

These behaviors may become stricter in a future version. Send values matching the published OpenAPI schema rather than relying on the fallback.

### 401 Unauthorized

Returned when API-key authentication fails.

```json theme={null}
{
  "data": {},
  "message": "Missing authorization header.",
  "status": 401
}
```

Common causes:

* missing `Authorization` header;
* a scheme other than the case-sensitive `Bearer` scheme;
* a token that does not contain `API_KEY_ID:API_KEY_SECRET`;
* an invalid, revoked, or inactive API key.

Correct format:

```bash theme={null}
curl -H "Authorization: Bearer api_xxx:sk_xxx" \
  https://api.probalytics.io/api/v1/markets
```

### 403 Forbidden

Returned when the authenticated account cannot access the requested resource.

### 500 Internal Server Error

Returned when a request could not be completed because of an internal or upstream database failure.

```json theme={null}
{
  "data": {},
  "message": "Failed to fetch markets.",
  "status": 500
}
```

Retry transient 5xx failures with bounded exponential backoff. If failures persist, contact support with the request parameters and UTC timestamp.

## REST limits versus ClickHouse quotas

No fixed REST requests-per-second or requests-per-hour quota is currently part of the public REST contract. Operational protections can still reject abusive or unusually concurrent traffic.

Direct ClickHouse credentials use separate traffic and resource limits. See [SQL access tiers](https://docs.probalytics.io/docs/sql-guide/overview.md#access-tiers). A ClickHouse quota error is not a REST 429 response and does not use the JSON format on this page.

## Cursor pagination

Pagination uses `cursor`; there is no `offset` parameter. A cursor is emitted whenever the current page contains exactly `limit` rows. The API does not fetch an extra row to prove another page exists, so a full final page can produce a cursor whose next request returns an empty `data` array.

Continue until `data` is empty or `next_cursor` is absent:

```python theme={null}
import requests

url = "https://api.probalytics.io/api/v1/fills"
headers = {"Authorization": "Bearer api_xxx:sk_xxx"}
params = {"limit": 1000, "platform": "POLYMARKET"}
all_rows = []

while True:
    response = requests.get(url, headers=headers, params=params, timeout=30)
    response.raise_for_status()
    payload = response.json()

    rows = payload["data"]
    if not rows:
        break

    all_rows.extend(rows)

    cursor = payload.get("next_cursor")
    if not cursor:
        break
    params["cursor"] = cursor
```


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.