Pagination and Errors

Every list endpoint paginates the same way and every non-2xx response wraps the same envelope. This page documents those shared conventions so per-resource pages can stay focused on resource-specific fields.

Pagination

List endpoints use a 1-based page index plus a page size:

The response is wrapped in the standard {rows, pagination} envelope:

{
  "data": {
    "rows": [
      { "id": 12, "name": "..." },
      { "id": 13, "name": "..." }
    ],
    "pagination": {
      "page": 1,
      "pageSize": 500,
      "total": 18,
      "totalPages": 1
    }
  }
}

To iterate through every row, increment page until page > totalPages.

Response envelope

Every API response — success and failure alike — wraps its payload in a standard envelope. On success, the resource (or list envelope above) is placed under data. On failure, the envelope carries the error code, the human-readable message and the request id.

{
  "success": false,
  "code": "APIf006",
  "message": "Field username exceeds the maximum length of 30 characters.",
  "data": ["username", 30],
  "request_id": "<request-id>"
}

Error catalogue

The platform exposes a stable, prefix-based error catalogue. Codes are emitted by the server in the same deployment and are stable across releases — consult the OpenAPI spec for the exact per-operation reference.

Branch on the code for coarse handling; consult per-resource pages for the codes a given operation can produce. Legacy uppercase variants (APIF517, APIF519, SYSF008) still appear in older payloads and are equivalent to the lowercase family.

HTTP status codes

Request id

Every response includes X-Request-Id and echoes the same value in request_id on failure. Operators include this id in support tickets so the platform team can pull the matching server-side log.

X-Request-Id: <request-id>

Retry guidance

Retry only on transient failures:

When retrying mutations, send the same Idempotency-Key so the server can deduplicate. See API Overview for the idempotency contract.

FAQ