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}/attendeesinstead: one request returns up to 100.
Errors
Errors are JSON, with a code and the request's ID:
{ "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.