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