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

# Response Patterns

> Standard success, pagination, and error envelopes for the Merchants API.

Successful Merchants API responses use a consistent JSON envelope. List endpoints add pagination fields under `data`. Errors use a dedicated error object.

## Single-item response

When an endpoint returns one resource, the body looks like:

```json theme={null}
{
  "data": { }
}
```

Optional fields on some success responses:

* `error`: boolean, set when the request failed (normally omitted on success)
* `message`: human-readable status text when present

## Paginated response

List endpoints wrap a page of results:

```json theme={null}
{
  "data": {
    "items": [{ }, { }],
    "next": 2,
    "total": 10,
    "last_update": "2021-01-01T00:00:00Z"
  }
}
```

| Field              | Meaning                                                                |
| ------------------ | ---------------------------------------------------------------------- |
| `data.items`       | Resources on the current page                                          |
| `data.next`        | Next page number when more results exist                               |
| `data.total`       | Total matching items across all pages                                  |
| `data.last_update` | Timestamp of the most recently updated item in the set, when available |

Common list query parameters (when supported by the endpoint):

| Parameter         | Meaning                                  |
| ----------------- | ---------------------------------------- |
| `page`            | 1-based page number (default 1)          |
| `limit`           | Page size (default 100, maximum 100)     |
| `since` / `until` | Inclusive `created_at` bounds (RFC3339)  |
| `sort`            | `asc` or `desc` for the primary sort key |

Exact parameters differ per endpoint: see each operation in the interactive reference.

## Error response

Failed requests return an error envelope:

```json theme={null}
{
  "error": {
    "code": 400,
    "message": "Insufficient quantity",
    "errors": [
      {
        "domain": "orders",
        "reason": "InsufficientQuantity"
      }
    ]
  }
}
```

| Field           | Meaning                                                    |
| --------------- | ---------------------------------------------------------- |
| `error.code`    | Application / HTTP-style error code                        |
| `error.message` | Primary human-readable message                             |
| `error.errors`  | Optional list of more specific `domain` / `reason` entries |

## HTTP status codes

| Range   | Meaning                                             |
| ------- | --------------------------------------------------- |
| **2xx** | Success                                             |
| **4xx** | Client error (invalid input, auth, not found, etc.) |
| **5xx** | Server or upstream failure                          |

Treat non-2xx responses as failures even if a body is present. Prefer handling by status code and `error.code` / `error.message` rather than string matching alone.

## Next

* [Authentication](/api/authentication)
* [API Overview](/api/overview)