> ## 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](/api-docs/updating-content#handle-the-outcome).

## Error codes

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

<h3 id="unauthenticated">
  `unauthenticated`
</h3>

**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.

<h3 id="forbidden">
  `forbidden`
</h3>

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

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

<h3 id="not-found">
  `not_found`
</h3>

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

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

<h3 id="workspace-not-found">
  `workspace_not_found`
</h3>

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

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

<h3 id="file-not-found">
  `file_not_found`
</h3>

**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=...`.

<h3 id="folder-not-found">
  `folder_not_found`
</h3>

**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=...`.

<h3 id="invalid-request">
  `invalid_request`
</h3>

**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.

<h3 id="invalid-id">
  `invalid_id`
</h3>

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

Do: use an id from an earlier response.

<h3 id="invalid-base-change">
  `invalid_base_change`
</h3>

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

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

<h3 id="invalid-cursor">
  `invalid_cursor`
</h3>

**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.

<h3 id="path-already-exists">
  `path_already_exists`
</h3>

**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](/api-docs/updating-content).

<h3 id="type-mismatch">
  `type_mismatch`
</h3>

**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.

<h3 id="folder-not-empty">
  `folder_not_empty`
</h3>

**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.

<h3 id="changes-in-review">
  `changes_in_review`
</h3>

**409.** The file, or a file in the folder, has changes that wait for review. Nothing was removed.

Do: resolve the changes in the app. See [Change reviews](/features/change-reviews). Then try again.

<h3 id="file-protected">
  `file_protected`
</h3>

**409.** The file is protected. Nothing was removed.

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

<h3 id="content-too-large">
  `content_too_large`
</h3>

**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.

<h3 id="service-unavailable">
  `service_unavailable`
</h3>

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

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

<h3 id="internal-error">
  `internal_error`
</h3>

**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                                 |
| List page size         | 1–1,000 items; default 100                     |
| Hybrid search results  | 1–500 files; default 10                        |
| Regex search results   | 1–500 files; default 50                        |
| Regex search query     | 1,024 characters, on a single line             |
| Regex matches returned | 50 lines per file                              |
| Regex line length      | Lines longer than 4,096 characters are skipped |

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.