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

# Errors and limits

Use HTTP status codes for program logic. The human-readable `detail` message is useful for diagnostics but can change.

## Error format

Errors use a JSON object with a `detail` field:

```json
{
  "detail": "Invalid or missing API key"
}
```

## Status codes

| Status | Meaning                                    | Recommended action                                                |
| ------ | ------------------------------------------ | ----------------------------------------------------------------- |
| `200`  | Request succeeded                          | Process the response. An empty `games` array is still successful. |
| `400`  | A filter or request value is invalid       | Correct the request; do not retry unchanged.                      |
| `401`  | API key is missing or invalid              | Check authentication; do not retry repeatedly.                    |
| `404`  | The requested game does not exist          | Refresh the game list or remove stale local state.                |
| `429`  | Request or stream connection limit reached | Wait and retry with backoff.                                      |
| `503`  | Stream capacity is temporarily unavailable | Retry with backoff.                                               |
| `5xx`  | Temporary server failure                   | Retry idempotent requests with bounded backoff.                   |

## Request limits

| Endpoint                   | Limit                                                           |
| -------------------------- | --------------------------------------------------------------- |
| REST game endpoints        | 200 requests per minute per API key                             |
| Stream connection attempts | 30 requests per minute per API key                              |
| Active streams             | Normally 3 per API key; your account may have a different limit |

Repeated failed reconnects can consume the stream connection-attempt limit. Add backoff instead of reconnecting in a tight loop.

## Retry strategy

For `429`, `503`, and temporary `5xx` responses:

1. Wait 1 second.
2. Double the delay after each failure: 1, 2, 4, 8 seconds.
3. Cap the delay at 30 seconds.
4. Add a small random jitter if many clients may reconnect together.
5. Reset the delay after a successful request or stream connection.

Do not automatically retry `400`, `401`, or `404` responses without changing the request or refreshing local state.

## Timeouts

Use a finite timeout for REST calls. A 10-second timeout is a reasonable starting point.

SSE is intentionally long-lived, so do not apply a short total-response timeout. Instead, monitor incoming events. A heartbeat is normally sent every 30 seconds; reconnect if no event arrives for more than 60 seconds.
