# The response envelope, pagination and errors

URL: https://kywi-docs-production.up.railway.app/integrating/the-response-envelope-pagination-and-errors
Type: docPage

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 columns

## 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.

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" } }

## the router’s own two failures

## details is not always an array

`details` is passed through untyped, and different guards put different things in it. `VALIDATION_ERROR` sends an array of `{ path, message }`; `TRANSITION_DENIED` sends an object `{ role, from, to, requiredRole }`; `FORBIDDEN_FIELD` sends `{ fields: [...] }`; `TOO_MANY_REQUESTS` sends `{ retryAfter }`, seconds until the account unlocks. Typing it as an array works until the first status, field or lockout refusal.

{ "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" } } }

## two 400/403 bodies, side by side

## There is no global rate limit — but four routes limit themselves

Four routes enforce a limit on their own callers: the public form-submit route (`POST /forms/:slug/submit`) tracks submissions per IP and answers `RATE_LIMITED` at 429 past the default of 10 per 15 minutes — but only when a proxy supplies `x-forwarded-for` or `x-real-ip`; without either, the check never runs. `POST /auth/forgot-password` tracks per email and answers the same code at 3 per hour; and the brute-force lockout shared by `POST /auth/login` and the self-service password change at `POST /users/:id/password` answers `TOO_MANY_REQUESTS` at 429 once too many bad attempts land against one account — both gated on brute-force tracking being configured; omit it and the lockout is skipped entirely. What is actually missing is a *global* limit: the `rateLimitPerMinute` stored on an OAuth client is a recorded value no code path reads to refuse a request, and core's own general-purpose rate limiter has no caller anywhere in the codebase. So ordinary reads and writes are unthrottled — budget your own concurrency for those. See [Caching semantics for an integrator](/integrating/caching-semantics-for-an-integrator/).
