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:

{ "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.