> For clean Markdown of any page, append .md to the page URL.
> For a complete documentation index, see https://docs.whalehunt.net/llms.txt.
> For AI client integration (Claude Code, Cursor, etc.), connect to the MCP server at https://docs.whalehunt.net/_mcp/server.

# Errors and reset

Read `retryable` on each error frame. The code alone does not authorize repeated attempts. Your last locally committed checkpoint is the safe recovery boundary.

| Code                  | Meaning                                        | Action                                                                    |
| --------------------- | ---------------------------------------------- | ------------------------------------------------------------------------- |
| `unauthenticated`     | Authentication rejected                        | Check the current key with the operator; stop frequent retries            |
| `forbidden_scope`     | Scope not permitted                            | Narrow the request or arrange the entitlement                             |
| `invalid_filter`      | Unsupported shape, selector or catalog binding | Correct the request; do not silently remove a predicate                   |
| `subscription_limit`  | Subscription or reservation capacity exhausted | Follow retryability; consider lease expiry and retained snapshots         |
| `cursor_mismatch`     | Wrong filter/subscription/binding              | Restore exact parameters or explicitly choose a new start                 |
| `cursor_expired`      | Cursor below the retained floor                | Handle reset; do not automatically jump live                              |
| `history_unavailable` | Previous history unavailable                   | Stop continuation and determine available history                         |
| `resume_overloaded`   | Replay resources unavailable now               | If retryable, use finite backoff with the same token                      |
| `slow_consumer`       | Send or unacknowledged window exceeded         | Improve processing and resume from committed state                        |
| `ack_invalid`         | ACK not valid for the active session/boundary  | Check connection, generation, token and local commit                      |
| `source_degraded`     | Source observation problem                     | Inspect quality snapshot and quality events                               |
| `server_unavailable`  | Request cannot currently be served             | Preserve token; bounded retry if permitted, otherwise operator assistance |

Closing a socket need not immediately release every reservation. Avoid reconnect storms when a lease has not expired.

## Error frame

This complete synthetic shape illustrates a rejected authentication; it is not a captured session response.

```json
{"version":1,"frameSequence":"2","kind":"error","code":"unauthenticated","retryable":false}
```

Only `code` and `retryable` are defined beyond the common envelope. V1 does not promise `message`, `reason` or `requestId` fields.

## Reset frame

The normal reader path reports `cursor_expired` and `history_unavailable` through `reset_required`, though these codes also belong to the error schema. This complete synthetic shape does not authorize a new live start.

```json
{
  "version": 1,
  "frameSequence": "3",
  "kind": "reset_required",
  "code": "cursor_expired",
  "streamId": "22222222-2222-4222-8222-222222222222",
  "historyGeneration": "33333333-3333-4333-8333-333333333333",
  "retainedFloor": "100",
  "permittedActions": ["discover_current_history", "explicit_live_cut"]
}
```

`retainedFloor` is required, with a decimal string or null. Stream/history IDs are required non-nil UUIDs. Actions are exactly the two strings shown, in that order; they do not name HTTP endpoints. Resolve the history with the operator and record an explicitly accepted gap before starting live. See [retention/reset](/polymarket/stream/retention).

## Transport closure

A broken socket can prevent delivery of the error itself. Recovery must work from saved state without a final JSON error. Record transport symptoms using [safe diagnostics](/polymarket/operations/troubleshooting), without tickets, tokens or raw payloads.