Rate Limits & Errors

The API applies per-minute rate limits per key and request category.

Limits

Category	Requests / minute
Reads	600
Writes	60
Analytics	30
AI generation	10

Writes and generation are intentionally stricter.

Rate-limit headers

Every response includes X-RateLimit-Limit, X-RateLimit-Remaining, and X-RateLimit-Reset.

When you hit the limit

The API returns 429 with a Retry-After header. Wait that many seconds before retrying, and use exponential backoff for long-running automations.

Error shape

All errors return { "error": { "code": "...", "message": "..." }, "request_id": "req_…" }.

Status	Code	Meaning
401	`unauthorized`	Missing or invalid key
403	`missing_scope`	Key lacks the required scope
404	`not_found`	Resource does not exist in your academy
409	`idempotency_conflict`	Same `Idempotency-Key`, different body
422	`validation_error`	Invalid request fields
429	`rate_limit_exceeded`	Rate limit hit — see `Retry-After`