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

# Response Format

> Success and error response envelopes with full field descriptions.

All Partner API responses use a consistent JSON envelope.

***

## Success — Single Resource

```json theme={null}
{
  "success": true,
  "data": { }
}
```

| Field     | Type            | Description              |
| --------- | --------------- | ------------------------ |
| `success` | boolean         | Always `true` on success |
| `data`    | object \| array | Response payload         |

### Example — Booking Status

```json theme={null}
{
  "success": true,
  "data": {
    "bookingId": "11111111-0000-0000-0000-000000000001",
    "status": "in progress",
    "paymentStatus": "PENDING",
    "externalReference": "ORDER-20260615-001"
  }
}
```

***

## Success — Paginated List

```json theme={null}
{
  "success": true,
  "data": [ ],
  "meta": {
    "page": 1,
    "limit": 20,
    "total": 142,
    "totalPages": 8
  }
}
```

| Field             | Type   | Description            |
| ----------------- | ------ | ---------------------- |
| `data`            | array  | Current page items     |
| `meta.page`       | number | Current page (1-based) |
| `meta.limit`      | number | Page size              |
| `meta.total`      | number | Total matching records |
| `meta.totalPages` | number | `ceil(total / limit)`  |

***

## Error Response

```json theme={null}
{
  "success": false,
  "error": {
    "code": "VALIDATION_ERROR",
    "message": "Human-readable description",
    "details": { },
    "requestId": "550e8400-e29b-41d4-a716-446655440000"
  }
}
```

| Field             | Type    | Description                                        |
| ----------------- | ------- | -------------------------------------------------- |
| `success`         | boolean | Always `false` on error                            |
| `error.code`      | string  | Machine-readable error code (see [Errors](errors)) |
| `error.message`   | string  | Human-readable summary                             |
| `error.details`   | object  | Optional validation details or extra context       |
| `error.requestId` | string  | Trace ID — include when contacting support         |

The same `requestId` is returned in the `X-Request-Id` response header.

***

## HTTP Status Codes

| Status | Meaning                                       |
| ------ | --------------------------------------------- |
| `200`  | Success (GET, PATCH, POST actions)            |
| `201`  | Created (booking)                             |
| `400`  | Validation error                              |
| `401`  | Missing or invalid API key                    |
| `403`  | Forbidden (permission or domain)              |
| `404`  | Resource not found                            |
| `409`  | Conflict (e.g. duplicate `externalReference`) |
| `422`  | Business rule violation                       |
| `429`  | Rate limit exceeded                           |
| `500`  | Internal server error                         |

***

## Validation Errors

When `error.code` is `VALIDATION_ERROR`, `error.details` may contain field-level messages from `class-validator`:

```json theme={null}
{
  "success": false,
  "error": {
    "code": "VALIDATION_ERROR",
    "message": "Validation failed",
    "details": {
      "message": [
        "contactId must be a UUID",
        "date must be a valid ISO 8601 date string"
      ]
    },
    "requestId": "..."
  }
}
```

***

## Null & Omitted Fields

* Optional fields may be omitted or `null` depending on the endpoint.
* Empty arrays are returned as `[]`, not `null`.
* Monetary amounts are numbers in **SAR** with up to two decimal places in API output.