# Rate limits, pagination, and errors

## Rate limits[​](#rate-limits "Direct link to Rate limits")

The API enforces rate limits to protect server resources and ensure fair usage.

Rate limits apply per IP address. Specific limits vary and may change. When you exceed the rate limit, the API returns `429 Too Many Requests`.

### Handling rate limits[​](#handling-rate-limits "Direct link to Handling rate limits")

Best practices:

* **Exponential backoff** - wait 1s, then 2s, then 4s between retries
* **Batch writes** - use `/tickets/multi` with arrays instead of one request per record
* **Cache schemas** - app schemas change rarely; cache them locally
* **Use filters** - narrow queries with `rlx` filters instead of fetching everything

## Pagination[​](#pagination "Direct link to Pagination")

Use `limitRecords` and `skipRecords` to page through large result sets.

### Parameters[​](#parameters "Direct link to Parameters")

| Parameter      | Type   | Default | Description      |
| -------------- | ------ | ------- | ---------------- |
| `limitRecords` | number | 10      | Records per page |
| `skipRecords`  | number | 0       | Records to skip  |

### Example[​](#example "Direct link to Example")

```
# Page 1 (records 1-50)
POST /api/w/IT/a/TICKET/tickets/list
{"limitRecords": 50, "skipRecords": 0}

# Page 2 (records 51-100)
POST /api/w/IT/a/TICKET/tickets/list
{"limitRecords": 50, "skipRecords": 50}

# Page 3 (records 101-150)
POST /api/w/IT/a/TICKET/tickets/list
{"limitRecords": 50, "skipRecords": 100}
```

### Total count[​](#total-count "Direct link to Total count")

Add `withTechnicalData=true` as a query parameter to get record counts in the response:

```
POST /api/w/IT/a/TICKET/tickets/list?withTechnicalData=true
```

Response includes:

```
{
  "data": [...],
  "filteredRecordsCount": 125,
  "unfilteredRecordsCount": 150
}
```

* `filteredRecordsCount` - total records matching your `rlx` filter
* `unfilteredRecordsCount` - total records in the app (ignoring filters)

## Timeouts[​](#timeouts "Direct link to Timeouts")

API requests time out after **30 seconds**. If your query is too complex or returns too much data, narrow it with:

* More specific `rlx` filters
* Smaller `limitRecords`
* Fewer fields in `listOfFields` (use specific field names instead of `"ALL"`)

## Request size limits[​](#request-size-limits "Direct link to Request size limits")

Request body size limits depend on the connection type. MCP connections enforce a **100 KB** body limit. For the REST API, practical limits are governed by server configuration and may differ across deployments.

## Error handling[​](#error-handling "Direct link to Error handling")

### HTTP status codes[​](#http-status-codes "Direct link to HTTP status codes")

| Code  | Meaning                                              |
| ----- | ---------------------------------------------------- |
| `200` | Success                                              |
| `400` | Bad request - invalid parameters or filter syntax    |
| `401` | Unauthorized - missing or invalid token              |
| `403` | Forbidden - insufficient permissions                 |
| `404` | Not found - workspace, app, or record does not exist |
| `429` | Too many requests - rate limit exceeded              |
| `500` | Internal server error                                |

### Common errors and solutions[​](#common-errors-and-solutions "Direct link to Common errors and solutions")

| Error                      | Cause                             | Solution                                                  |
| -------------------------- | --------------------------------- | --------------------------------------------------------- |
| Invalid filter syntax      | Missing quotes around strings     | Use `state="open"` not `state=open`                       |
| Empty results              | User lacks workspace/app access   | Verify token user's permissions                           |
| Record not found           | Wrong workspace or app alias      | Check the slug format: `WORKSPACE/APP`                    |
| Request timeout            | Query too broad or data too large | Add `rlx` filters, reduce `limitRecords`                  |
| Permission denied on write | User cannot perform the action    | Verify the user's group permissions and available actions |
| 401 on write               | Token expired or invalid          | Refresh or regenerate the token                           |