API

Errors and pagination

Handle Coop Problem Details responses and stable opaque cursors.

Problem Details

API errors use application/problem+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"
}
StatusType suffixMeaning
400invalid_requestA field, body, limit, or parameter is invalid
400invalid_cursorThe cursor is malformed or belongs to another collection
401unauthorizedThe token is missing, malformed, unknown, expired, or revoked
403forbiddenThe token lacks the route scope or target access
404not_foundThe requested accessible resource does not exist
409idempotency_conflictAn idempotency key was reused with different message input
409relay_not_readyThe selected route cannot currently send
503search_unavailableContact 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:

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