Rate limits, headers & errors

Primicornis is designed for honest operator automation, not unmanaged scraping. Limits are enforced at the workspace + token plane so we can graduate into paid tiers without breaking integrations.

Current enforcement (rolling deployment)

Surface	Policy
Reads (GET)	Generous sustained baseline with burst allowance
Writes (POST/PATCH/DELETE)	Lower sustained ceiling; bulk imports throttled further
Search	Tightest burst control (prevents enumeration)
Imports	Concurrency cap per workspace; additional jobs queue

Implementation note: Per-token counters and 429 responses are being rolled out alongside API token GA. Until quotas are wired end-to-end, rely on exponential backoff whenever you receive 429 or transient 5xx.

Standard error shape

json

{
  "error": {
    "code": "forbidden",
    "message": "You do not have access to this workspace."
  }
}

Code	Meaning
`401`	Missing/invalid Cognito session or API token
`403`	Authenticated but not permitted for workspace/role
`404`	Resource or workspace not found
`409`	Conflicts (duplicate slug, version mismatch)
`422`	Validation errors (Zod/OpenAPI)
`429`	Quota exceeded — slow down, honor `Retry-After` when present
`5xx`	Retry with jittered backoff

Planned response headers

Header	Purpose
`X-RateLimit-Limit`	Burst or sustained allowance
`X-RateLimit-Remaining`	Decaying counter per window
`X-RateLimit-Reset`	Unix timestamp for window reset
`Retry-After`	Seconds to wait after `429`

Documentation will mirror production headers verbatim once the middleware lands in API releases.

Abuse prevention principles

No silent bulk export — large pulls through list endpoints should be time-distributed.
Imports are asynchronous-friendly; never parallelize unchecked apply jobs.
Automation tokens should be short-lived operationally (rotate quarterly).

Monetization readiness

Quota telemetry is bucketed per token and workspace so we can:

Offer Starter / Growth / Enterprise plans with soft limits.
Sell overage packs without changing integration code.
Flag noisy neighbors for review before they impact shared infrastructure.