# Limits, paging and errors

## Rate limits

Each token gets a per-minute budget, by kind of call:

- **Lists** (any endpoint that returns a page of rows): 60 calls a minute
- **Single reads**: 300 calls a minute
- **Writes**: 120 calls a minute

Your account as a whole gets three times each budget across all its tokens. Creating more tokens doesn't raise the limit.

Going over returns `429` with a `Retry-After` header giving the number of seconds to wait. Wait that long before trying again; retrying right away won't help.

## Paging

List endpoints return 25 rows by default. Send `limit` for between 1 and 100. Each page carries `has_more` and `next_cursor`. To get the next page, send `next_cursor` back as `cursor` with the same filters. `next_cursor` is `null` on the last page.

## Errors

Every error has the same body:

```json
{ "code": "invalid_request", "message": "limit must be between 1 and 100.", "field": "limit", "request_id": "9b2f4c1e-..." }
```

- **400 `invalid_request`**: something in the request is wrong. `field` names it when there's one to name. An unknown query parameter is refused too, so a typo doesn't get silently ignored.
- **401 `unauthorized`**: the token is missing, wrong, revoked or expired.
- **403 `missing_scope`**: the token works but wasn't granted the scope this call needs. Create a token with that scope.
- **404 `not_found`**: there's no such record, or it belongs to another agent. The API doesn't tell these apart.
- **429 `rate_limited`**: see *Rate limits*.
- **500 `internal_error`**: something broke on our side.

If you contact support about a failed call, include its `request_id`. It's in every error body and in every response's `X-Request-Id` header, and it lets us find that exact call.