Skip to main content

​
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

FieldDescription
dataThe resource object or array of resources.
meta.requestIdUnique identifier for the request. Include this when contacting support or filing bug reports.
meta.timestampISO 8601 timestamp generated by the server when the response was produced.
paginationPresent on list endpoints only. Contains page, limit, total, and totalPages.
error.codeMachine-readable error category (e.g. validation_error, not_found). Use this for programmatic branching.
error.messageHuman-readable explanation suitable for logs or developer-facing output.
error.detailsOptional array of field-level validation errors. Each entry contains field and message.

​
Status codes

​
Success codes

CodeMeaningWhen used
200 OKRequest succeeded.Reads, updates, and operational actions.
201 CreatedResource created.POST endpoints that create a new resource (e.g. cases, re-referrals).
204 No ContentAction completed, no body returned.DELETE endpoints.

​
Error codes

CodeMeaningWhen used
400 Bad RequestInvalid input.Malformed payloads, invalid state transitions, unsupported file types.
401 UnauthorizedAuthentication failed.Missing, expired, or invalid credentials.
403 ForbiddenInsufficient permissions.Role or ownership restrictions, environment-level access controls.
404 Not FoundResource does not exist.The referenced ID could not be resolved.
409 ConflictConflicting state.Duplicate resources or invalid state transitions.
429 Too Many RequestsRate 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.