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

# Response envelope

> Every Partner API response uses the same outer shape.

Whether you got a `200` with data, a `4xx` validation error, or a `5xx`
downstream failure, the response body has the same outer shape:
`request_id` at the top level, plus either `data` (on success) or `error`
(on failure).

## Success

```json theme={null}
{
  "request_id": "e35321ccab165d147bd584900966dc16",
  "data": { /* endpoint-specific payload */ }
}
```

## Error

```json theme={null}
{
  "request_id": "43c5ad17b9e660b4d463b512e2bf2346",
  "error": {
    "code": "request_invalid",
    "message": "brand_id and branch_id must be passed together or omitted together",
    "details": { /* optional, per-error */ }
  }
}
```

`error.code` is a stable machine-readable identifier — use it for branching
in your code. `error.message` is human-readable and may be polished over
time, so don't pattern-match on it.

`request_id` is in every response. Include it when you open a support
ticket; it lets klikit pinpoint the exact request in our logs. Treat its
format as **opaque** — the production format today is 32-char hex, but
older paths and the development environment may return UUID-prefixed
strings like `req_e9f2b838-38e9-43ba-9e30-9b747da67d9f`. Don't validate
it client-side.

## Status code conventions

| Code                | Meaning                                                                     |
| ------------------- | --------------------------------------------------------------------------- |
| `200`, `201`, `204` | Success                                                                     |
| `400`               | Request invalid — body, headers, or query parameters didn't validate        |
| `401`               | Credentials missing, malformed, or revoked                                  |
| `403`               | Authenticated but the credential lacks the required scope                   |
| `404`               | Resource not found, or not visible to this credential                       |
| `409`               | Conflict — most commonly an `Idempotency-Key` re-used with a different body |
| `422`               | Semantically invalid (e.g. status transition not allowed)                   |
| `429`               | Rate-limited — back off and retry                                           |
| `5xx`               | Klikit-side failure. Retry with backoff; raise a ticket if it persists      |

A non-2xx response **always** has an `error` object. A 2xx response **always**
has a `data` field (it may be `null`, `{}`, or `[]`).

## Pagination — note the inconsistency

Endpoints that return lists wrap their `data` in a paginated object with
`page`, `size`, and `total`. The key holding the actual items **varies by
endpoint**:

| Endpoint        | Items live under                                           |
| --------------- | ---------------------------------------------------------- |
| `GET /orders`   | `data.orders`                                              |
| `GET /branches` | `data.results`                                             |
| `GET /brands`   | `data[0].brands` (legacy shape — `data` is an outer array) |

This is an artefact of partner-api forwarding to multiple backend services
that each have their own conventions. We don't normalise — what you see in
the [API Reference](/partner-api/api-reference) is what the service
returns. Treat the shape per endpoint, not in general.