> ## Documentation Index
> Fetch the complete documentation index at: https://docs.casexchange.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Response Format

> Response envelopes, pagination metadata, and error conventions used across the CaseXchange Public API

## 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:

```json theme={null}
{
  "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:

```json theme={null}
{
  "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:

```json theme={null}
{
  "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.