Response Format

Response envelopes

Every response from the CaseXchange Public API uses a consistent envelope so clients can parse success and error cases with minimal branching.

Success envelope (single resource)

Endpoints that return a single resource wrap it in data alongside a meta object:

{
  "data": {
    "id": "case_8201",
    "status": "open",
    "createdAt": "2026-03-15T09:30:00.000Z"
  },
  "meta": {
    "requestId": "req_f2dbe1d3f6ad4a7bb5b4c9f2",
    "timestamp": "2026-03-31T12:00:00.000Z"
  }
}

Success envelope (list with pagination)

List endpoints return an array in data and include a pagination object:

{
  "data": [
    { "id": "case_8201", "status": "open" },
    { "id": "case_8202", "status": "closed" }
  ],
  "pagination": {
    "page": 1,
    "limit": 20,
    "total": 50,
    "totalPages": 3
  },
  "meta": {
    "requestId": "req_a1b2c3d4e5f6",
    "timestamp": "2026-03-31T12:00:00.000Z"
  }
}

204 No Content

DELETE endpoints return 204 No Content with no response body. Clients should treat any 2xx without a body as a successful deletion.

Error envelope

All error responses share a single shape built around the error object:

{
  "error": {
    "code": "validation_error",
    "message": "Request validation failed",
    "details": [
      { "field": "email", "message": "must be a valid email address" }
    ]
  },
  "meta": {
    "requestId": "req_err123456",
    "timestamp": "2026-03-31T12:00:00.000Z"
  }
}

Key fields

Field	Description
`data`	The resource object or array of resources.
`meta.requestId`	Unique identifier for the request. Include this when contacting support or filing bug reports.
`meta.timestamp`	ISO 8601 timestamp generated by the server when the response was produced.
`pagination`	Present on list endpoints only. Contains `page`, `limit`, `total`, and `totalPages`.
`error.code`	Machine-readable error category (e.g. `validation_error`, `not_found`). Use this for programmatic branching.
`error.message`	Human-readable explanation suitable for logs or developer-facing output.
`error.details`	Optional array of field-level validation errors. Each entry contains `field` and `message`.

Status codes

Success codes

Code	Meaning	When used
`200 OK`	Request succeeded.	Reads, updates, and operational actions.
`201 Created`	Resource created.	`POST` endpoints that create a new resource (e.g. cases, re-referrals).
`204 No Content`	Action completed, no body returned.	`DELETE` endpoints.

Error codes

Code	Meaning	When used
`400 Bad Request`	Invalid input.	Malformed payloads, invalid state transitions, unsupported file types.
`401 Unauthorized`	Authentication failed.	Missing, expired, or invalid credentials.
`403 Forbidden`	Insufficient permissions.	Role or ownership restrictions, environment-level access controls.
`404 Not Found`	Resource does not exist.	The referenced ID could not be resolved.
`409 Conflict`	Conflicting state.	Duplicate resources or invalid state transitions.
`429 Too Many Requests`	Rate limit exceeded.	The client has sent too many requests in a given time window.

Implementation tips

Branch on error.code, not error.message. The code value is stable across releases; message text may change.
Treat error.details as optional. Not every error includes field-level detail. Always check for its presence before iterating.
Handle both 200 and 201 on success. Creation endpoints return 201; most other writes return 200. Accept any 2xx as success.
Preserve unknown fields. If you proxy or log payloads, do not strip unrecognized keys. The schema may add new fields in future releases without a version bump.

Overview

Authentication

Core Concepts

Integration Guides

Core Examples

Extended Examples

Response envelopes

Success envelope (single resource)

204 No Content

Error envelope

Key fields

Status codes

Success codes

Error codes

Implementation tips

​Response envelopes

​Success envelope (single resource)

​Success envelope (list with pagination)

​204 No Content

​Error envelope

​Key fields

​Status codes

​Success codes

​Error codes

​Implementation tips

Response envelopes

Success envelope (single resource)

Success envelope (list with pagination)

204 No Content

Error envelope

Key fields

Status codes

Success codes

Error codes

Implementation tips