# 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 secret. 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.
Most refused requests, such as `404 not_found` and `400 invalid_request`, count
toward the 120 too.

-   The limit counts each of a key's secrets on its own. A key has one secret,
    or two for up to 24 hours after a rotation (the old one running out).
-   Every request counts once, reading one attendee
    (`/events/{event_id}/attendees/{attendee_id}`) included. To read many
    attendees, page through `/events/{event_id}/attendees` instead: one
    request returns up to 100.

## 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.