Errors and limits

Error envelope

1{ "error": { "code": "invalid_request", "message": "query: too small", "requestId": "..." } }

Codes never change meaning; new ones may be added. Send requestId when you report a problem.

Code	Status
`invalid_request`	400
`unauthenticated`	401
`forbidden`	403
`not_found`	404
`conflict`	409
`payload_too_large`	413
`idempotency_mismatch`	422
`rate_limited`	429
`internal`	500

Limits

What	Limit
Requests per key	600 a minute, bursts up to 120
Events per request	100
One event payload or text	256 KB
All events in one request	1 MB
JSON nesting	64 levels
Query	8,000 characters
Recall budget	default 2,000 tokens, max 32,000
Webhooks per project	10
Events in one `POST /v1/imports`	2,000 (the CLI has no cap)
Records in one export	50,000, then `truncated: true`
Exports per key	10 an hour

429 responses carry Retry-After. Rate-limit state is on every response in X-RateLimit-Limit and X-RateLimit-Remaining.

Idempotency

Events carry an idempotency key, unique per project. Reusing a key with the same content returns the original; reusing it with different content is a 422. The SDKs add a key to every remember so a retry is safe.

Scopes

read, write, read_write, forget, admin. admin grants everything. A key can only create keys with scopes it holds.