Errors and limits

Error response format

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

{
  "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:

{
  "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.

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.

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

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

`changes_in_review`

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. Then try again.

`file_protected`

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

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

Get started

Using the API

Files

Folders

Search

Errors and limits

Error response format

Field errors

Reads and writes fail differently

Retry rules

Error codes

`unauthenticated`

`forbidden`

`not_found`

`workspace_not_found`

`file_not_found`

`folder_not_found`

`invalid_request`

`invalid_id`

`invalid_base_change`

`invalid_cursor`

`path_already_exists`

`type_mismatch`

`folder_not_empty`

`changes_in_review`

`file_protected`

`content_too_large`

`service_unavailable`

`internal_error`

Limits

​Error response format

​Field errors

​Reads and writes fail differently

​Retry rules

​Error codes

​unauthenticated

​forbidden

​not_found

​workspace_not_found

​file_not_found

​folder_not_found

​invalid_request

​invalid_id

​invalid_base_change

​invalid_cursor

​path_already_exists

​type_mismatch

​folder_not_empty

​changes_in_review

​file_protected

​content_too_large

​service_unavailable

​internal_error

​Limits

Error response format

Field errors

Reads and writes fail differently

Retry rules

Error codes

`unauthenticated`

`forbidden`

`not_found`

`workspace_not_found`

`file_not_found`

`folder_not_found`

`invalid_request`

`invalid_id`

`invalid_base_change`

`invalid_cursor`

`path_already_exists`

`type_mismatch`

`folder_not_empty`

`changes_in_review`

`file_protected`

`content_too_large`

`service_unavailable`

`internal_error`

Limits