> ## Documentation Index
> Fetch the complete documentation index at: https://docs.usealmanac.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Errors and pagination

> Handle API failures consistently and page through list responses.

## Error envelope

Validation, authentication, permission, conflict, not-found, and provider errors
raised by Almanac use one JSON shape:

```json theme={"theme":{"light":"github-light","dark":"vesper"}}
{
  "error": "not_found",
  "message": "wiki was not found",
  "request_id": "req_..."
}
```

Use `error` for program control, show `message` to a developer, and include
`request_id` when reporting a failure.

Framework-level unknown routes and unsupported methods can instead return a
`detail` response. Integrations should still handle an unexpected non-JSON or
non-Almanac error body defensively.

## Pagination

Job lists, page lists, page search, source lists, and source search use `limit`
and `offset` query parameters:

```bash theme={"theme":{"light":"github-light","dark":"vesper"}}
curl --get "$ALMANAC_API_URL/v1/wikis/$WIKI_ID/pages" \
  -H "Authorization: Bearer $ALMANAC_TOKEN" \
  --data-urlencode "limit=50" \
  --data-urlencode "offset=0"
```

`limit` defaults to `50` and accepts `1` through `500`; `offset` starts at `0`.
Increase the offset by the number of records returned. Stop when a response
contains fewer records than the requested limit. Responses are plain arrays and
do not include a total or next cursor.

## Common failure boundaries

* `401`: the bearer token is missing, expired, or invalid.
* `403`: the key is valid but lacks the required workspace permission.
* `404`: the resource or page path does not exist.
* `403`: the caller lacks permission, including access to the requested wiki.
* `400`: an identifier, query, or request body failed validation.
* `409`: the requested write conflicts with existing state.
* `503`: a required provider is temporarily unavailable.

See [Troubleshooting](/reference/troubleshooting) for CLI symptoms and the
[generated endpoint reference](/api-reference/workspaces/workspaces) for exact schemas.