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

# Errors and limits

> Handle API errors, review outcomes, retries, and content limits.

## Error response format

Public API errors use the content type `application/problem+json` and this body:

```json theme={null}
{
  "type": "https://docs.qontext.ai/errors/path-already-exists",
  "title": "Path already exists",
  "status": 409,
  "code": "path_already_exists",
  "detail": "Something already exists at that path.",
  "requestId": "01JQ8H2XN4KP7VBR3TFY6ZC9SD"
}
```

| Field | Use |
| - | - |
| `code` | Stable machine code. **Branch on this.** |
| `type` | Stable URI for this kind of failure. It links to the section for the code on this page. You can also branch on this. |
| `status` | The same as the HTTP status. |
| `title` | Human label. Do not branch on it. |
| `detail` | Human explanation. Safe to show. Do not branch on it. |
| `requestId` | Locates the call in our logs. Send it to us when you ask for help. |
| `errors` | Present when specific inputs are at fault. One entry per field. |

`requestId` is also in the `X-Request-Id` response header on every call, success or failure.

## Field errors

When specific inputs are at fault, the `errors` array names each one. This excerpt shows the relevant fields:

```json theme={null}
{
  "code": "invalid_request",
  "status": 400,
  "errors": [
    {
      "code": "out_of_range",
      "pointer": "/limit",
      "detail": "limit must not be greater than 1000"
    }
  ]
}
```

`pointer` is a JSON Pointer to the member. `/limit` is the `limit` query parameter. `/content` is the `content` member of the body.

## Reads and writes fail differently

Reading an individual file or folder without access returns `404`. Lists and searches omit items the key cannot read. A write that the key may not perform answers `403 forbidden`.

## Retry rules

* Retry a `503`. Wait for `Retry-After` if the response includes it. Before retrying a write with an uncertain outcome, read the live state.
* Do not retry a `4xx`. Fix the request.
* Do not retry a `202` from `PUT /v1/files/{id}/content`. It is not an error. See [Updating content](https://docs.qontext.ai/api-docs/updating-content.md#handle-the-outcome).

## Error codes

Each `type` URI in an error body points to one section below.

### `unauthenticated`

**401.** The API key is missing or not valid.

Do: check the `Authorization: Bearer` header. Create a new key in the app if the key was revoked.

### `forbidden`

**403.** This key may not perform this write.

Do: check the permissions of the key in the app. See [Access management](https://docs.qontext.ai/features/access-management.md).

### `not_found`

**404.** The requested resource was not found.

Do: check the URL and resource identifier, and confirm that the key has access.

### `workspace_not_found`

**404.** No workspace matches this key.

Do: create a new key in the workspace you want to write to.

### `file_not_found`

**404.** No such file, or none this key can read.

Do: check the id. Look the file up by path with `GET /v1/files?path=...`.

### `folder_not_found`

**404.** No such folder, or none this key can read. Also answered for a destination folder that does not exist on a move or a create, and for a `parent_id` that names no folder on `GET /v1/folders`.

Do: check the id. Look the folder up by path with `GET /v1/folders?path=...`.

### `invalid_request`

**400.** A parameter or member is unknown or malformed. Also answered when a `PATCH` sends two fields, or none.

Do: read `errors`. Each entry names the field with a JSON Pointer.

### `invalid_id`

**400.** The id is not of the form `doc_…`, `dir_…`, or `chg_…`.

Do: use an id from an earlier response.

### `invalid_base_change`

**400.** `baseChangeId` is not a change of this file.

Do: read the file again. Send the `lastChangeId` it reports.

### `invalid_cursor`

**400.** The cursor is malformed, or was issued for a query with other filters.

Do: start again from the first page. Keep the same filters for every page.

### `path_already_exists`

**409.** A file or folder is already at that path. Nothing was overwritten.

Do: choose another path, or use the existing resource if that is your intent. To replace an existing file's content, read it first and follow [Updating content](https://docs.qontext.ai/api-docs/updating-content.md).

### `type_mismatch`

**409.** The path names the wrong kind of resource for this parameter. For example, a folder path where a file path is required.

Do: a file path ends in `.md`. A folder path does not. Send the correct kind.

### `folder_not_empty`

**409.** The folder still has contents. Nothing was removed.

Do: send `recursive=true` to delete the folder with everything below it. Or delete the contents first.

### `folder_protected`

**409.** The folder you are deleting, or a folder inside it, is protected. The protection can come from the folder's own flag or from a folder above it. Nothing was removed.

Do: remove the protection in the app, then try again. See [Change reviews](https://docs.qontext.ai/features/change-reviews.md).

### `file_protected`

**409.** The file is protected, or sits inside a protected folder. On a folder delete, a protected file inside the folder answers this too. Nothing was removed.

Do: remove protection before deleting the file. A key inheriting an owner’s or admin’s permissions can change a file's own `protected` with [Update a file](https://docs.qontext.ai/api-docs/files/update-file.md). Otherwise, ask a member with Full access to remove protection in the app.

### `content_too_large`

**422.** The content is longer than 51,200 characters.

Do: read `errors` for the length you sent and the limit. Split the content into smaller files.

### `too_many_edits`

**422.** The request exceeds a write or deletion limit. Nothing is saved.

Do: split the write into smaller batches. If the error names a review limit, change fewer existing files in each batch. Recursive folder deletion is limited to **500 files and folders combined**, including the selected folder; delete larger trees in smaller steps.

### `service_unavailable`

**503.** The workspace is temporarily unreachable.

Do: wait for `Retry-After` if present, then try again.

### `internal_error`

**500.** An unexpected failure. We already have a report.

Do: inspect the live state before retrying a write. Send [support](mailto:support@qontext.ai) the `requestId` if the failure repeats.

## Limits

| Limit | Value |
| - | - |
| File content | 51,200 characters of Markdown or plain text |
| File or folder name | 255 characters |
| Recursive folder deletion | 500 files and folders combined per request, including the selected folder |
| List page size | 1–1,000 items; default 100 |
| Hybrid search results | 1–500 passages or files, according to `mode`; default 10 |
| Regex search results | 1–500 passages or files, according to `mode`; default 10 |
| Regex search query | 1,024 characters, on a single line |

Use names without spaces or other whitespace; hyphens are a safe separator. Shell metacharacters are also rejected. Folder names cannot start with a dot. Names cannot contain `/`, `\`, or control characters, and cannot be `.` or `..`. File names end in lowercase `.md`; folder names do not.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.