Response Envelope

Every Nova API response uses one of three shapes. Build your client around
this contract — it is enforced globally on the server side and lint-checked
in our codebase.

Single resource

{
  "data": { "uuid": "…", "name": "Acme Distribution", "type": "BRANCH" }
}

The data field contains the resource directly. There is no wrapping or
metadata for single-resource responses.

Paginated collection

{
  "data": [ { … }, { … }, { … } ],
  "pagination": {
    "total": 1247,
    "page": 1,
    "limit": 20,
    "totalPages": 63,
    "hasNext": true,
    "hasPrev": false
  }
}

pagination.total is the unfiltered total in the result set, not the count of
items on the current page. Use hasNext / hasPrev for pagination UI;
use page and limit to construct the next request.

Error

{
  "error": {
    "code": "VALIDATION_FAILED",
    "message": "Invalid input data",
    "details": {
      "fields": {
        "email": "must be a valid email address"
      }
    },
    "requestId": "req_01H…"
  }
}

code is a stable, machine-readable identifier — switch on it in your
client. message is human-readable and may change wording without a
breaking-change notice. details is shape-stable per code (see
Errors for the catalogue). requestId is the value to quote
when contacting support.

Bypass cases

A handful of endpoints return non-JSON bodies (binary downloads, OAuth
redirects). These are explicitly documented in the reference and are the
only exceptions to the envelope rule.