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

# Authentication & Errors

> Auth requirements, validation behavior, and caching semantics

## Authentication model

* `/health` and `/` are public.
* Every `/v1/*` endpoint requires `Authorization: Bearer <token>`.
* Tokens are validated against your API key records.

Missing token response:

```json theme={null}
{
  "error": "Unauthorized",
  "message": "Expected Authorization: Bearer <token>"
}
```

Invalid token response:

```json theme={null}
{
  "error": "Unauthorized",
  "message": "Invalid API token"
}
```

## Validation errors (`400`)

Query parameter validation errors return:

```json theme={null}
{
  "error": "BadRequest",
  "message": "limit must be an integer between 1 and 500"
}
```

Examples:

* `provider` must be `kalshi` or `polymarket`
* `status` must be `open` or `closed`
* `expand` (events endpoint) must be exactly `markets`

## Server errors (`500`)

Unhandled errors return:

```json theme={null}
{
  "error": "InternalServerError",
  "message": "Unexpected error"
}
```

## Caching behavior

For successful `GET /v1/*` responses, the API returns:

```http theme={null}
Cache-Control: private, max-age=60, stale-while-revalidate=30
```

For `401` and `403` responses on `/v1/*`, the API returns:

```http theme={null}
Cache-Control: no-store
```