# Errors and pagination

> Handle Coop Problem Details responses and stable opaque cursors.


## Problem Details

API errors use `application/problem+json`:

```json
{
  "type": "urn:coop:error:forbidden",
  "title": "forbidden",
  "status": 403,
  "detail": "The requested resource is outside the token's contact access.",
  "request_id": "request-id"
}
```

| Status | Type suffix | Meaning |
| --- | --- | --- |
| `400` | `invalid_request` | A field, body, limit, or parameter is invalid |
| `400` | `invalid_cursor` | The cursor is malformed or belongs to another collection |
| `401` | `unauthorized` | The token is missing, malformed, unknown, expired, or revoked |
| `403` | `forbidden` | The token lacks the route scope or target access |
| `404` | `not_found` | The requested accessible resource does not exist |
| `409` | `idempotency_conflict` | An idempotency key was reused with different message input |
| `409` | `relay_not_ready` | The selected route cannot currently send |
| `503` | `search_unavailable` | Contact search is temporarily unavailable |

Keep the `request_id` when reporting a failure. Error responses never contain message content, credentials, or token-verifier details.

## Cursor pagination

Collection responses contain:

```json
{
  "data": [],
  "page": {
    "next_cursor": null,
    "has_more": false
  }
}
```

`limit` defaults to 50 and accepts 1 through 100. When `has_more` is true, send the returned `next_cursor` unchanged as the next request's `cursor`. A cursor is opaque and bound to its Organization and collection. Do not parse, edit, or reuse it on another endpoint.

Recent conversations use `(last_message_at, recipient_id)` ordering. Messages use `(source_timestamp, id)` ordering. This keeps traversal stable when newer records arrive before the page currently being read.

