Skip to content

The response envelope, pagination and errors

Three response envelopes cover the whole API — `{ data }`, `{ data, meta }`, `{ error }` — and `meta.hasMore` is what says you are not seeing everything.

Every REST route answers in one of three shapes, and no route invents a fourth. A single object comes back as { "data": … }; a collection comes back as { "data": [...], "meta": {…} }; a failure comes back as { "error": { "code", "message" } } with an optional details. Even the router's own two failures — an unmatched path and a wrong method — use the error shape too.

The collection envelope

meta is always the same five fields, whether the route paginates or answers with the whole collection.

GET /api/v1/content/page?siteId=default&limit=2&sort=path — rows trimmed to five columnsjson
{
  "data": [
    { "id": "929644e4-5c81-445e-b0d4-b7df3c453fdf", "title": "Home", "slug": "home", "path": "/", "status": "published" },
    { "id": "43e9242e-f7c4-4b59-a1b1-9ec105bfc02b", "title": "A/B testing", "slug": "ab-testing", "path": "/ab-testing/", "status": "published" }
  ],
  "meta": { "total": 12, "page": 1, "pageSize": 2, "totalPages": 6, "hasMore": true }
}

What meta carries

The five fields on every collection response. hasMore is the single field that says "you are not looking at everything" — an integration that reads once and stops has no other reliable way to tell a complete answer from the first page of a larger one.
NameTypeDefaultDescription
hasMoreboolean—

The only field to branch on. Everything else is arithmetic you could get wrong; this one says outright whether rows exist beyond what you are holding.

totalnumber—

Rows matching the filters, across all pages.

pagenumber—

The clamped page actually served, not the one you asked for.

pageSizenumber—

The clamped limit actually applied. On a whole-collection route it is the row count itself.

totalPagesnumber—

0 — not 1 — when total or pageSize is zero. An empty collection reports zero pages.

A route that returns its whole collection in one response — media, feeds, components, audiences, experiments, menus, users, webhooks, sites — wears the same envelope deliberately: page: 1, pageSize equal to the row count, hasMore: false. That false is a promise rather than a coincidence.

Limits are clamped, not defaulted

page and limit are forced into range rather than rejected: page to at least 1, limit to between 1 and 100, defaulting to 10. ?limit=5000 is not an error — it silently serves 100, and only meta.pageSize tells you so.

Filtering has a matching sharp edge. On a content list, page, limit, sort, dir, status, locale, siteId, parentId, search, slug and path are reserved; any other query parameter that happens to match a declared field name on that content type becomes an exact-match filter on it, and anything else is dropped without comment. A typo'd parameter silently narrows your results or does nothing.

Offset-addressed routes such as search compute hasMore from the offset you actually used rather than from page arithmetic, so ?offset=5&limit=20 reports honestly instead of over-claiming what is left.

Errors

Switch on error.code, never on message. The codes worth switching on include NOT_FOUND (404), UNAUTHORIZED (401), FORBIDDEN (403), VALIDATION_ERROR (400), BAD_REQUEST (400 — a body that failed to parse as JSON), LOCKED (423), TRANSITION_DENIED and FORBIDDEN_FIELD (both 403), RATE_LIMITED and TOO_MANY_REQUESTS (both 429 — see below), plus METHOD_NOT_ALLOWED (405) and a NOT_FOUND carrying the message Route not found (404) from the router itself. This is not exhaustive, but it covers what a general-purpose client needs to branch on.

the router’s own two failuresjson
{ "error": { "code": "NOT_FOUND", "message": "Route not found" } }
{ "error": { "code": "METHOD_NOT_ALLOWED", "message": "Method not allowed" } }
two 400/403 bodies, side by sidejson
{ "error": { "code": "VALIDATION_ERROR", "message": "Validation failed",
    "details": [ { "path": "", "message": "Unrecognized key(s) in object: 'siteId'" } ] } }

{ "error": { "code": "TRANSITION_DENIED",
    "message": "Role 'author' may not change content status from 'draft' to 'published'. That transition requires role 'editor' or higher.",
    "details": { "role": "author", "from": "draft", "to": "published", "requiredRole": "editor" } } }