Get started

Errors and rate limits

Errors share one JSON shape. Branch on code and the HTTP status; internal failure details are never returned.

{
  "defined": false,
  "code": "UNAUTHORIZED",
  "status": 401,
  "message": "missing"
}

defined is true when the error is one a procedure declares. Validation errors may carry a data object describing the failing fields.

StatusMeaning

400Invalid input, wrong value type, archived definition, self-merge, or a capability that is not configured.

401Missing or invalid key.

403Disabled or expired key, no membership, paused workspace access, missing scope or role, or a restricted module.

404Unknown route, or a record that does not exist in this workspace. Read collections at /data/{resource}, such as /data/icps; records at /data/{resource}/{id}. Discover operation names and input schemas at /capabilities, then use /query for reads or /operations for writes and paid work.

409Slug collision, idempotency-key conflict, or a retryable transaction conflict.

429Rate limit exceeded. Respect Retry-After.

500Infrastructure failure. Retry writes with the same Idempotency-Key.

Rate limits

300 requests per minute per key and 1,000 per minute per workspace. Successful checks expose X-RateLimit-Limit and X-RateLimit-Remaining; a 429 adds Retry-After in seconds. If the limiter is unavailable the API fails open and omits the headers.

Background operations have a separate ceiling: at most 5 active per key and 20 per workspace.