Usage, retries, and errors

Pagination and filtering

Collection responses use count, next, previous, and results. The default page size is 50, with a maximum of 100. Follow next; do not assume all records fit in one response. Only use filters and ordering parameters listed for the endpoint. Resource names are plural and hyphenated. Project-owned resources sit below /projects/{project_id}/.

Request limits

Allowance	Default
Per key	120 requests/minute
Shared workspace	600 requests/minute
Shared expensive operations	10 requests/minute

Expensive operations include file-upload preparation/finalisation and outbound business actions. Bulk imports, exports, and document generation must use the expensive allowance when exposed in the external contract. Check the reference for available operations; an internal app feature does not imply external API support.

All keys and service accounts share the workspace allowance. Creating or rotating keys does not reset it. Support can tune limits for an approved integration. Service accounts remain free; normal storage and feature entitlements still apply.

For 429, wait at least the Retry-After seconds, then retry with exponential backoff and jitter. A quota-store outage returns 503; it does not grant unlimited access. Limit concurrency and avoid repeated full-workspace polling.

Safe POST retries

Every POST requires an Idempotency-Key of at most 200 characters. Use a new random value or stable integration operation ID for each new operation. Retain it when retrying an identical request.

Results are retained for 24 hours, scoped to the service account and workspace, including across key rotation. Reusing a key with another URL, body, query, or changed effective permissions returns 409. An identical completed retry returns the stored result with Idempotency-Replayed: true.

A concurrent or interrupted operation can return 409 while its outcome is unresolved. Do not generate a new key to bypass it: check the resource and contact support with the request ID. This prevents duplicate actions when a response is lost. After 24 hours the key can be reused, so retries beyond that window require reconciling the original result first.

Errors

{
  "error": {
    "code": "insufficient_scope",
    "message": "Missing required permissions or key scopes.",
    "request_id": "9ee67e33-9bbd-4909-96f4-5cc546c43a65"
  }
}

Validation errors can also contain fields. Responses include X-Request-Id; include it when contacting support. Missing/invalid keys return 401, access restrictions 403, inaccessible records 404, and invalid business transitions or idempotency conflicts 409 where applicable.

If a valid key fails, check beta access, account suspension, expiry, key scopes, role permissions, project assignments, and enabled workspace modules before retrying. Reads may remain available under the application's existing data-export policy when a subscription expires; writes do not.

Files

Use the listed presign → upload → finalise flow. Upload file bytes to the returned storage URL, then finalise through the API. Multipart POST bodies are not supported by v1's JSON idempotency flow. Presigned links expire; keep them private and request a new operation when the original upload opportunity has expired.

Units and delivery details

Before creating an order request, read GET /api/v1/workspaces/{workspace_id}/libraries/units/ and use one of the returned canonical UUIDs in unit. Include description, a positive quantity_needed, required_on_site_date, and an order_type for freehand requests. The unit list follows the workspace’s active choices and uses standard pagination.

Material purchase orders using site delivery require both delivery_address and required_by_date. Business transitions continue to enforce the application’s approval, compliance, and contract rules; a valid key does not bypass those rules.

File finalisation

After uploading to the returned presigned storage location, call the file’s finalize action with an idempotency key. A successful finalisation returns 202 Accepted and the file detail. Read the file detail to monitor processing; the accepted response does not mean background processing is complete. File deletion retains the application’s normal audit and evidence policy.