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.
{
"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
| Name | Type | Default | Description |
|---|---|---|---|
hasMore | boolean | — | 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. |
total | number | — | Rows matching the filters, across all pages. |
page | number | — | The clamped page actually served, not the one you asked for. |
pageSize | number | — | The clamped limit actually applied. On a whole-collection route it is the row count itself. |
totalPages | number | — |
|
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.
{ "error": { "code": "NOT_FOUND", "message": "Route not found" } }
{ "error": { "code": "METHOD_NOT_ALLOWED", "message": "Method not allowed" } }{ "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" } } }