# Pagination and Errors

Every list endpoint on the Amdahl Platform API follows the same shape, and every error response follows the same envelope. Code once against the conventions on this page and you will not have to special-case individual tools.

## List endpoint conventions

The public list endpoints — `GET /chats`, `GET /routines`, `GET /agents` — share the same paging parameters:

| Parameter | Type    | Default | Max   | Purpose             |
| --------- | ------- | ------- | ----- | ------------------- |
| `limit`   | integer | `50`    | `200` | Page size           |
| `offset`  | integer | `0`     | n/a   | Zero-indexed offset |

And the same envelope shape: a named collection array plus the paging facts (values are echoed back clamped if you overshot):

```json
{
  "chats": [ ... ],
  "total": 147,
  "limit": 50,
  "offset": 0
}
```

- The collection key matches the resource: `chats` on `/chats`, `routines` on `/routines`, `agents` on `/agents`.
- `total`: total matching rows across all pages. Authoritative; safe for UI pagers.
- There is no `has_more` field — derive it client-side: `offset + rows.length < total`.
- `GET /agents` returns the merged roster (Amdahl library + workspace agents) without paging — it is bounded small by construction.

### Paging example

```bash
# First page
curl -s "$AMDAHL_BASE/chats?limit=50&offset=0" \
  -H "X-API-Key: $AMDAHL_KEY"

# Next page
curl -s "$AMDAHL_BASE/chats?limit=50&offset=50" \
  -H "X-API-Key: $AMDAHL_KEY"
```

A client-side pager can simply walk `offset` by `limit` while `offset + rows.length < total`.

## Filtering and sorting

Filters are per-endpoint, not a generic vocabulary:

| Endpoint | Filters |
| --- | --- |
| `GET /chats` | `status` (e.g. `?status=complete`) |
| `GET /routines` | `enabled` (e.g. `?enabled=true`) |

Ordering is fixed per endpoint — Chats list newest activity first, Routines newest first — there is no `order_by` parameter on the public surface. An unsupported query parameter is ignored or returns `invalid_argument`, never silently reinterpreted.

## Error envelope

Every non-2xx response uses the same JSON envelope:

```json
{
  "error": {
    "code": "invalid_input",
    "message": "Human readable description of what went wrong.",
    "details": {
      "field": "scopes",
      "issue": "must be a non-empty array"
    }
  }
}
```

- `code`: a machine-readable string from the catalogue below.
- `message`: a short human-readable description. Safe to surface in UIs.
- `details`: optional object with structured context. Shape depends on `code`.

Clients should branch on `code`, never on the exact text of `message`. HTTP status is included but is a coarser signal than `code`.

## Standard error codes

| Code               | HTTP | When                                                                                        | Expected client reaction                                         |
| ------------------ | ---- | ------------------------------------------------------------------------------------------- | ---------------------------------------------------------------- |
| `unauthenticated`  | 401  | Missing or invalid credential                                                               | Reauthenticate, do not retry the exact call                      |
| `forbidden`        | 403  | Credential valid but lacks required scope or access to the resource                         | Check `details.missing_scope`, rotate with higher scopes or stop |
| `not_found`        | 404  | Target resource does not exist or is outside the caller's business                          | Treat as terminal; do not retry                                  |
| `invalid_input`    | 400  | Request body failed schema validation                                                       | Fix the payload; do not retry the same body                      |
| `invalid_argument` | 400  | Syntactically valid request whose semantics are wrong (bad sort field, out-of-range values) | Fix arguments; do not retry the same call                        |
| `conflict`         | 409  | State conflict (for example revoking a key already revoked, double-approving an outline)    | Refetch current state; reconcile                                 |
| `rate_limited`     | 429  | Rate limit exceeded                                                                         | Back off; see [rate-limits.md](./rate-limits.md)                 |
| `internal`         | 500  | Server error                                                                                | Retry with backoff for 5xx only                                  |

The full, continuously-generated catalogue of codes plus details keys lives at [api-reference/errors.md](./api-reference/errors.md).

## Retry strategy

- **Retry:** `internal` (5xx) and `rate_limited` (429). Use exponential backoff with jitter. Start at 500ms, double each attempt, cap at 30 seconds, give up after 5 attempts unless your workload can tolerate more.
- **Do not retry:** every other `4xx`. `invalid_input`, `forbidden`, `not_found`, and `conflict` all mean "this exact call will not succeed". Retrying wastes quota and can trigger `rate_limited` on top of the original failure.
- **Honor `Retry-After`.** When present on a 429 or 503 response (in seconds), wait that long before the next attempt.

Example `rate_limited` body:

```json
{
  "error": {
    "code": "rate_limited",
    "message": "Rate limit exceeded for POST /search.",
    "details": {
      "limit": 60,
      "window_seconds": 60,
      "retry_after_seconds": 12
    }
  }
}
```

## Idempotency

POST endpoints that create resources (`POST /chat`, `POST /routines`, `POST /agents`) are not yet idempotent at the server level. A successful-but-timed-out first attempt plus a retry can create two records (two Chats, two routines).

Until a server-side `Idempotency-Key` header lands (tracked in [changelog.md](./changelog.md) as a planned feature), deduplicate on the client:

- For Chats: name the Chat deterministically and list with `GET /chats` before retrying a START; if the named Chat already has a fresh run, poll it instead of starting another.
- For agents: pass an explicit `slug` on create — a retry that raced a success returns a typed `slug_conflict` instead of creating a duplicate, which makes create effectively idempotent per slug.
- For routines: list `GET /routines` and match on `name` before re-creating.

`PATCH` updates, `DELETE`s, resume, and cancel are naturally idempotent and safe to retry — a repeat resume against a run that already resumed returns `invalid_state`, not a double-apply.

## Reference

- Full error code catalogue with `details` shapes: [api-reference/errors.md](./api-reference/errors.md).
- Rate limit windows and headers: [rate-limits.md](./rate-limits.md).
- Per-tool filter, sort, and response shapes: the [tool catalog](./api-reference/tool-catalog.md) and the [API reference](./api-reference).