## Pagination

List endpoints use offset-based pagination with two query parameters:

| Parameter | Description | Default | Max |
| --- | --- | --- | --- |
| `limit` | Number of records to return | `100` | `100` |
| `offset` | Number of records to skip | `0` | — |

Every list response includes a `meta` object with the total count so you can page through results:

```
{
  "data": [ /* ... */ ],
  "meta": {
    "total": 250,
    "limit": 100,
    "offset": 0
  }
}
```

To fetch the next page, increase `offset` by your `limit` (for example, `?limit=100&offset=100`).

### Filtering

Some list endpoints accept filters. For example, [`GET /payments`](https://help.trykarat.com/api-reference/payments/list-payments) supports `recipientId`, `batchId`, and `referenceId`.

## Status codes

The API uses standard HTTP status codes:

| Status | Meaning |
| --- | --- |
| `200` | Success |
| `201` | Resource created |
| `400` | Bad request — validation failed or malformed input |
| `401` | Unauthorized — missing or invalid API key |
| `404` | Not found — the resource does not exist |
| `500` | Internal server error |

## Errors

Non-success responses return a consistent error envelope:

```
{
  "error": {
    "message": "amount: amount must be positive",
    "code": "optional_error_code"
  }
}
```

Validation errors (`400`) include a human-readable `message` that names the offending field, making it easy to surface back to your users.