# Limits and errors

Source: https://blocklive.io/docs/developers/limits-and-errors

How much you can ask for, and what every error means.

## Limits

| Limit           | Value                                             |
| --------------- | ------------------------------------------------- |
| Requests        | 120 a minute per key. Other keys aren't affected. |
| Rows a page     | 1 to 100 (`?limit=`, default 100).                |
| Page cursor     | Can be used for 15 minutes.                       |
| Check-in cursor | Can be used for 24 hours.                         |

Over 120 requests in a minute you get `429 rate_limited` with a `Retry-After`
header: the seconds until the next minute starts. Wait that long, then carry on.

## Errors

Errors are JSON, with a code and the request's ID:

```json
{ "error": { "code": "rate_limited", "request_id": "6f9e…" } }
```

Quote the `request_id` when you contact Blocklive.

| Status | Code                 | Meaning                                                                                        | What to do                                         |
| ------ | -------------------- | ---------------------------------------------------------------------------------------------- | -------------------------------------------------- |
| 400    | `invalid_request`    | A query parameter is wrong or not allowed, or `limit` is outside 1 to 100.                     | Fix the request.                                   |
| 401    | `unauthorized`       | No key, a malformed key, or a key that is revoked, expired or for the other environment.       | Check the key; ask the organizer.                  |
| 404    | `not_found`          | The path, event or attendee doesn't exist, or your key can't read it. These aren't told apart. | Check the IDs and the key's events.                |
| 405    | `method_not_allowed` | Only `GET` is supported.                                                                       | Use `GET`.                                         |
| 410    | `resync_required`    | The cursor is too old, or what your key may read changed.                                      | Start again without a cursor.                      |
| 429    | `rate_limited`       | Over 120 requests a minute.                                                                    | Wait for `Retry-After`.                            |
| 503    | `unavailable`        | Blocklive couldn't answer just now.                                                            | Retry with backoff: 1 s, 2 s, 4 s, up to a minute. |

Retrying is safe: every endpoint only reads.