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

# Conventions

> Pagination, errors, and rate limiting across the API.

## Pagination

List endpoints return a common envelope:

```json theme={null}
{ "data": [ ... ], "has_more": true }
```

* **Cursor pagination** (`limit` + `after_id`) — collections, chat sessions, and messages. Pass the last item's `id` as `after_id` to fetch the next page.
* **Offset pagination** (`skip` + `limit`) — collection files, which additionally return `count` (total matches) to support sorted, filterable tables.

## Errors

Error responses carry a structured envelope alongside the legacy `detail` field:

```json theme={null}
{
  "detail": "Collection not found",
  "error": {
    "type": "not_found_error",
    "message": "Collection not found",
    "request_id": "1f2e3d4c5b6a7980"
  }
}
```

<Note>`error` is the canonical shape; `detail` is retained for backward compatibility and will be removed in a future API version.</Note>

| Status | `error.type`            | Meaning                                                  |
| ------ | ----------------------- | -------------------------------------------------------- |
| `400`  | `invalid_request_error` | Malformed request or invalid parameters                  |
| `401`  | `authentication_error`  | Missing or invalid API key                               |
| `403`  | `permission_error`      | The key lacks permission for this action                 |
| `404`  | `not_found_error`       | Resource does not exist or is not accessible             |
| `409`  | `conflict_error`        | Conflicts with existing state (e.g. duplicate name)      |
| `413`  | `file_too_large`        | Upload exceeds the 100 MB limit                          |
| `422`  | `invalid_request_error` | Request body failed validation                           |
| `429`  | `rate_limit_error`      | Too many requests — retry after the `Retry-After` header |
| `5xx`  | `api_error`             | Server error — safe to retry with backoff                |

Include `error.request_id` when contacting support about a failed request.

## Rate limiting

Requests are rate-limited per account. When throttled, the API returns `429` with a `Retry-After` header expressing the wait in seconds.