# API errors and pagination

AppBarn resource endpoints under `/api/*` use UTF-8 JSON. The one deliberate media-type exception is `GET /api/install/:ticket/manifest.plist`, which is the F08 Apple OTA plist response (`application/xml; charset=utf-8`). Errors, including errors from that route, use the normal JSON envelope.

## Errors

```json
{
  "error": {
    "code": "stable_code",
    "message": "safe message",
    "fields": { "field": "optional validation detail" }
  },
  "request_id": "server-generated-request-id"
}
```

`fields` is optional and bounded. `X-Request-Id` carries the same server-generated request ID. Client-provided request IDs are never authoritative. Keep the request ID when reporting an unexpected failure; never include bearer tokens, request bodies or signed URLs.

Common statuses: `400`, `401`, `403`, `404`, `409`, `413`, `415`, `426`, `429`, and `5xx`.

## JSON mutations

- `Content-Type: application/json` is required before feature logic runs.
- request bodies must be valid UTF-8;
- common maximum body size is 64 KiB; a feature may declare a smaller limit;
- unknown and prototype-like object keys are rejected;
- feature handlers consume validated typed schema output only.

## Workspace context

Human requests operating in a Workspace send exact lowercase UUIDv4 `X-AppBarn-Workspace-Id`. The server reloads current membership; the header selects context and never grants access. Automation Tokens pin one Workspace; a supplied Workspace header must match that credential exactly.

## Pagination

Lists use bounded pages: default 50, never above 100. `next_cursor` is an opaque, query-shape-bound value. Do not decode, edit or reuse it with different filters. New F15 cursors use a versioned UTF-8-safe encoding; the server temporarily accepts the immediately preceding cursor format for rollout compatibility.

## CLI exit categories

The CLI preserves API code/request ID and maps failures to stable non-zero categories: `2` input/protocol, `3` authentication, `4` authorization/not-visible, `5` conflict, `6` quota/rate, `7` server/provider, `1` local/unknown.

## Related

- [CLI errors](/cli/errors)
- [Authentication troubleshooting](/troubleshooting/auth-token)