> For the complete documentation index, see [llms.txt](https://sm-fund.gitbook.io/sm-fund-docs/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://sm-fund.gitbook.io/sm-fund-docs/reference/errors.md).

# Errors and close codes

Use the HTTP response for a failed ticket request or failed WebSocket upgrade. Once the upgrade succeeds, use the WebSocket close code and reason to decide whether to refresh the ticket, fix the client, or retry.

## Ticket endpoint responses

The ticket endpoint is `POST https://sm.fund/v1/wss/tickets`.

| Status | Meaning                                                                | Client action                                                        |
| ------ | ---------------------------------------------------------------------- | -------------------------------------------------------------------- |
| `200`  | Ticket issued.                                                         | Use the returned `wss_url`, `feed`, and `subprotocol`.               |
| `401`  | Missing or invalid API key.                                            | Send a valid server-side `X-API-Key`; never use it on the WebSocket. |
| `403`  | The account is inactive or does not have the required WSS entitlement. | Restore account access or plan access, then request a new ticket.    |
| `422`  | The JSON body or `feed` value is invalid.                              | Send valid JSON and use `polymarket` or `raw`.                       |
| `429`  | The fixed-window ticket rate limit was exceeded.                       | Wait for the number of seconds in `Retry-After`, then retry.         |
| `503`  | The credential service is unavailable.                                 | Retry with backoff after the service recovers.                       |

The API key is accepted only in `X-API-Key` on this HTTPS request. The WebSocket ticket is a separate credential and is accepted only as `Authorization: Bearer <WSS_TICKET>` during the WebSocket handshake.

## WebSocket handshake responses

| Status | Meaning                                                                              | Client action                                                                |
| ------ | ------------------------------------------------------------------------------------ | ---------------------------------------------------------------------------- |
| `101`  | Upgrade accepted.                                                                    | Start receiving server-push frames.                                          |
| `400`  | The feed or explicitly requested WebSocket subprotocol is invalid or does not match. | Correct the URL and use the subprotocol returned for that feed.              |
| `401`  | The ticket is missing, invalid, expired, already consumed, or revoked.               | Request a new ticket and retry after fixing the access condition.            |
| `503`  | The service capacity is full for a new user.                                         | Retry with backoff; an existing connection is not displaced by this failure. |

An HTTP handshake failure does not replace an existing connection. A new valid connection for the same user does replace the existing one after registration, regardless of API key or feed.

## WebSocket close codes

| Code   | Reason                | Reconnect guidance                                                                                                          |
| ------ | --------------------- | --------------------------------------------------------------------------------------------------------------------------- |
| `4001` | `connection replaced` | Stop automatic reconnect. Another valid connection for the user is now active; retrying immediately would replace it again. |
| `4003` | `access expired`      | Request a fresh ticket and reconnect.                                                                                       |
| `4003` | `access revoked`      | Restore access or use an authorized key, request a fresh ticket, and reconnect.                                             |
| `1008` | `server push only`    | Remove application text/binary sends. Reconnect only after the client is corrected.                                         |
| `1013` | `client too slow`     | Reduce consumer/backlog pressure, then request a fresh ticket and reconnect.                                                |
| `1001` | `server shutdown`     | Reconnect with backoff when the service is available.                                                                       |

Tickets are single-use at the handshake reservation stage. After a normal network disconnect, obtain a new ticket instead of reusing the old one. A reconnect does not replay frames missed during the outage.