Pagination, Errors, and Rate Limits

Pagination

Most list endpoints accept:

• limit: number of items, bounded by the server.

• offset: zero-based offset.

Responses include a page object when the endpoint supports pagination.

Error envelope

Errors use one stable shape:

{
  "error": {
    "code": "forbidden",
    "message": "Resource access denied",
    "request_id": "uuid"
  }
}

Log request_id with the integration job and show it in support tickets.

Retry policy

Retry network failures and 408/429/5xx responses with exponential backoff and jitter. Do not retry 400, 401, 403, 404, or 422 without changing the request or authorization.

Idempotency

For create operations, use your own idempotency key in the integration layer and safely reconcile by name/metadata after timeouts. Do not assume a timed-out POST was not applied.

Rate limits

Respect 429 responses and keep concurrency bounded per key, Org, and workspace. Batch read operations, cache immutable metadata, and avoid polling faster than necessary.