Errors

Every non-2xx answer has the same body. error is a stable snake_case code you can branch on; message is for people and may change.

{
  "status_code": 403,
  "error": "missing_action",
  "message": "This needs the download action on the file",
  "path": "/api/v1/tenants/fitness-co/applications/fitness-app/files/01J9Z6S9Q5F5R6Y2W2GZ3B3K4D/download",
  "timestamp": "2026-10-22T09:30:00.000Z"
}

• message is a string, or an array of strings when several request fields are invalid.
• A 429 answer carries a Retry-After header with the seconds to wait.
• Retry 429, 500 and 503 with back-off. Do not retry other 4xx answers without changing the request.
• The Node client raises a typed error per status, each with .status, .code (the error value) and .body. See ccs-files-client.

The catalog below is generated from the service’s own list, so it cannot drift. Codes that any authenticated route can return before it does anything else are marked “Any authenticated route”. The conventions are in API conventions.

400 Bad request

depth_exceeded

When. The folder would be nested deeper than 32 levels.

What to do. Create it higher up in the tree.

Returned by. POST P/folders, PATCH P/folders/:folder_id, POST P/folders/:folder_id/copy

invalid_cursor

When. The after cursor is not one this service issued for this listing.

What to do. Pass the next_cursor of the previous answer unchanged, or omit after.

Returned by. GET P/folders/:folder_id/children, GET P/holds, GET P/search, GET P/webhooks/deliveries

invalid_json

When. The request body is not valid JSON.

What to do. Send well-formed JSON with Content-Type: application/json.

invalid_limit

When. limit is not a positive integer within the route's maximum.

What to do. Send an integer within the limit shown on the route.

Returned by. GET P/folders/:folder_id/children, GET P/holds, GET P/search, GET /platform/usage, GET /platform/tenants/:tenant_id/audit, GET P/webhooks/deliveries

invalid_move

When. A folder was moved into itself or one of its own descendants, or the root folder was moved or renamed.

What to do. Pick a target outside the folder's subtree.

Returned by. PATCH P/folders/:folder_id, POST P/folders/:folder_id/copy

invalid_name

When. A file or folder name is empty, longer than 255 characters, contains /, a control character, or is . or ...

What to do. Choose another name.

Returned by. POST P/folders, PATCH P/folders/:folder_id, POST P/uploads, PATCH P/files/:file_id

invalid_request

When. The request is malformed: a required field is missing, a value has the wrong type or format, or a field the route does not accept was sent. message lists every problem.

What to do. Fix the request body or parameters named in message and retry.

Returned by. 38 operations; each lists it in the API reference.

role_locked

When. The role is tenant_owner, which always holds every permission and cannot be changed.

What to do. Nothing to do: the owner already holds every permission.

Returned by. PUT P/permissions/roles/:role_id, PUT /tenants/:tenant_id/permissions/roles/:role_id

webhook_url_not_allowed

When. The webhook URL is not https, carries a user name or password, or points to (or resolves to) a private, loopback or link-local address.

What to do. Use a public https URL of your backend and authenticate deliveries with the signature, not with credentials in the URL.

Returned by. PUT P/webhooks

401 Unauthorized

invalid_token

When. The bearer token is missing, malformed, expired, signed by an unknown key, or has the wrong audience (aud must be files-api).

What to do. Request a token for the Files API resource (set resource to the resource identifier). Renew an expired token.

Returned by. Any authenticated route.

share_password_required

When. The share link is protected by a password and none was sent.

What to do. Ask the user for the password and send it as password.

Returned by. POST /shares/:token/download

403 Forbidden

cannot_grant_more_than_held

When. An access entry names actions the granter does not hold on the item.

What to do. Grant only actions you hold yourself, or ask a holder of files.manage.

Returned by. PUT P/folders/:folder_id/permissions, POST P/folders/:folder_id/permissions/entries, DELETE P/folders/:folder_id/permissions/entries/:entry_id, PUT P/files/:file_id/permissions, POST P/files/:file_id/permissions/entries, DELETE P/files/:file_id/permissions/entries/:entry_id

client_context_mismatch

When. The token's client belongs to another tenant or application than the one in the URL, or is unknown or inactive.

What to do. Call the context the client belongs to, or use a client of a platform application.

Returned by. Any authenticated route.

files_access_not_granted

When. The application switched the Files platform off at the Identity Server.

What to do. A tenant administrator enables Files for the application (Identity admin UI: the application, Platform Apps, Files).

Returned by. Any authenticated route.

folder_managed

When. The item is an application-managed folder or lies below one, and a person (a user token: the console, the tenant owner and files.manage holders included) tried to change it: upload, new version, new folder, rename, move in or out, copy into, metadata, status, trash, restore, delete, purge or permissions. Share links are refused inside a managed folder for everyone. managed_folder_id names the folder that carries the mark.

What to do. Let the application that manages the folder make the change through its backend. In an emergency the tenant owner can release the folder (POST P/folders/:folder_id/release-management on managed_folder_id).

Returned by. 24 operations; each lists it in the API reference.

insufficient_scope

When. A user token lacks files:access, a machine token carries none of files:manage, files:read, files:config.manage, or the route needs a scope the token does not carry.

What to do. Request the missing scope and make sure the client is granted it on the Files API resource at the Identity Server.

Returned by. Any authenticated route.

missing_action

When. The caller lacks the action (view, download, edit, share, delete, approve) on the item. Never says whether the item exists for someone else.

What to do. Ask someone who can share the item, or an administrator, to grant you the action.

Returned by. 58 operations; each lists it in the API reference.

missing_capability

When. The route needs a system-level permission key (settings, audit, the role matrix, purge) that none of the caller's roles carries in this application.

What to do. Ask the tenant owner to map the key onto one of your roles on the Permissions page.

Returned by. Any authenticated route.

no_application_access

When. The user has no access to the application in the URL.

What to do. Give the user access to the application in the Identity Server, then retry.

Returned by. Any authenticated route.

not_tenant_member

When. The user is not an active member of the tenant in the URL.

What to do. Check the tenant_id and the user's membership in the Identity Server.

Returned by. Any authenticated route.

partial_permission

When. A subtree operation (delete, restore) is blocked by descendants the caller cannot act on; blocked lists the first 100 ids.

What to do. Ask for the action on the listed items, or act on them one by one.

Returned by. DELETE P/folders/:folder_id

platform_admin_required

When. A /platform/* route was called by a user the Identity Server does not report as a platform administrator, or by a machine client that is not a Files platform client with files:config.manage.

What to do. Platform administration is for CCS operators only.

Returned by. 21 operations; each lists it in the API reference.

principal_not_allowed

When. The route is for user tokens only and a machine token called it, or the other way round; or a user token sent managed, which only a machine client may set on a folder.

What to do. Use the kind of token the route documents; mark or unmark a managed folder from your backend with its machine client.

Returned by. Any authenticated route.

share_password_invalid

When. The password sent for the share link is wrong. Three failures per minute per address are allowed.

What to do. Check the password with the person who shared the link.

Returned by. POST /shares/:token/download

tenant_not_available

When. The tenant in the URL is unknown, suspended or deleted at the Identity Server.

What to do. Check the tenant_id; a suspended tenant must be reactivated at the Identity Server.

Returned by. Any authenticated route.

tenant_owner_required

When. Only the tenant owner may grant or withdraw files.permissions.manage, and release an application-managed folder (POST P/folders/:folder_id/release-management).

What to do. Ask the tenant owner to make the change.

Returned by. PUT P/permissions/roles/:role_id, PUT /tenants/:tenant_id/permissions/roles/:role_id, POST P/folders/:folder_id/release-management

tenant_suspended

When. A platform administrator suspended the tenant's storage: new uploads and versions are refused; reading keeps working.

What to do. Contact the platform operator.

Returned by. POST P/uploads, POST P/files/:file_id/versions

404 Not found

application_not_found

When. The application in the URL is not an active application of the tenant.

What to do. Check the application_id.

Returned by. Any authenticated route.

entry_not_found

When. The item has no access entry with this id of its own (inherited entries are removed on the folder that holds them).

What to do. List the item's permissions and use the entry_id shown there.

Returned by. DELETE P/folders/:folder_id/permissions/entries/:entry_id, DELETE P/files/:file_id/permissions/entries/:entry_id

file_not_found

When. No file with this id exists in this application, or the caller cannot view its folder.

What to do. Check the file_id.

Returned by. POST P/uploads/:upload_id/complete, GET P/files/:file_id, PATCH P/files/:file_id, GET P/files/:file_id/download, GET P/files/:file_id/content, GET P/files/:file_id/preview, PUT P/files/:file_id/hold, DELETE P/files/:file_id/hold, POST /shares/:token/download

folder_not_found

When. No folder with this id exists in this application, or the caller cannot view its parent.

What to do. Check the folder_id; root is the application's root folder.

Returned by. POST P/folders, GET P/folders/:folder_id, PATCH P/folders/:folder_id, DELETE P/folders/:folder_id, GET P/folders/:folder_id/children, POST P/folders/:folder_id/copy, POST P/folders/:folder_id/release-management, POST P/uploads, PATCH P/files/:file_id, GET /shares/:token

job_not_found

When. No job with this id exists for this caller in this application.

What to do. Check the job_id returned by the 202 answer.

Returned by. GET P/jobs/:job_id

not_found

When. An id in the path is malformed, or the route does not exist.

What to do. Check the path and the ids.

Returned by. 102 operations; each lists it in the API reference.

rendition_not_available

When. The requested rendition does not exist (yet) for the file's version; rendition_status says why.

What to do. Wait for processing (file.ready), request another rendition, or regenerate renditions.

Returned by. GET P/files/:file_id/download, GET P/files/:file_id/content, POST /shares/:token/download

role_not_found

When. The role is not a role of the tenant that may carry Files permissions in this application.

What to do. Pick a role from GET P/principals/roles or the Permissions page.

Returned by. PUT P/permissions/roles/:role_id, PUT /tenants/:tenant_id/permissions/roles/:role_id

share_not_found

When. No share link with this id or token exists.

What to do. Check the link.

Returned by. DELETE P/shares/:share_id, GET /shares/:token, POST /shares/:token/download

storage_account_not_found

When. No storage account has this id.

What to do. List the accounts and use one of their ids, or default for the platform storage.

Returned by. GET /platform/storage-accounts/:storage_account_id, PATCH /platform/storage-accounts/:storage_account_id, DELETE /platform/storage-accounts/:storage_account_id, POST /platform/storage-accounts/:storage_account_id/verify, PUT /platform/tenants/:tenant_id/storage-account, POST /platform/tenants/:tenant_id/storage-migrations

storage_migration_not_found

When. No storage migration has this id.

What to do. List the tenant's migrations and use one of their ids.

Returned by. GET /platform/storage-migrations/:migration_id

taxonomy_not_found

When. Only categories and departments are managed value lists.

What to do. Use one of the two names.

Returned by. GET P/taxonomies/:name, PUT P/taxonomies/:name

upload_not_found

When. No upload ticket with this id exists for this caller in this application.

What to do. Check the upload_id; tickets of other callers are not visible.

Returned by. GET P/uploads/:upload_id, DELETE P/uploads/:upload_id, POST P/uploads/:upload_id/parts, POST P/uploads/:upload_id/complete

version_not_found

When. The file has no version with this number (it may have been pruned).

What to do. List the versions with GET P/files/:file_id/versions.

Returned by. PATCH P/files/:file_id, GET P/files/:file_id/download, GET P/files/:file_id/content, GET P/files/:file_id/preview, GET P/files/:file_id/versions/:version_no, PATCH P/files/:file_id/versions/:version_no, DELETE P/files/:file_id/versions/:version_no, POST P/files/:file_id/versions/:version_no/restore

409 Conflict

file_locked

When. Someone else holds a lock (check-out or edit session) on the file; lock describes it.

What to do. Wait for the lock to be released or to expire, or ask a holder of files.manage to break it.

Returned by. PATCH P/files/:file_id, DELETE P/files/:file_id, POST P/files/:file_id/purge, POST P/files/:file_id/versions, POST P/files/:file_id/versions/:version_no/restore

file_on_hold

When. The file is under a legal hold (hold describes it): it cannot be purged, its versions cannot be deleted or pruned, and the trash keeps it.

What to do. Ask a holder of files.manage to release the hold (DELETE …/files/:file_id/hold) once it is no longer needed.

file_pending

When. The file's upload has not been completed yet.

What to do. Complete the upload ticket first.

Returned by. DELETE P/files/:file_id, POST P/files/:file_id/copy, POST P/files/:file_id/purge, GET P/files/:file_id/download, GET P/files/:file_id/content, POST P/files/:file_id/versions, PUT P/files/:file_id/hold

file_quarantined

When. The file was found infected and is quarantined: it is never served.

What to do. Nothing to download. An administrator can purge it.

Returned by. PATCH P/files/:file_id, POST P/files/:file_id/copy, GET P/files/:file_id/download, GET P/files/:file_id/content, GET P/files/:file_id/preview, POST P/files/:file_id/versions

file_trashed

When. The file or folder is in the trash.

What to do. Restore it first.

Returned by. POST P/folders, PATCH P/folders/:folder_id, DELETE P/folders/:folder_id, POST P/folders/:folder_id/copy, POST P/uploads, PATCH P/files/:file_id, DELETE P/files/:file_id, POST P/files/:file_id/copy, POST P/files/:file_id/restore, GET P/files/:file_id/download, GET P/files/:file_id/content, GET P/files/:file_id/preview, POST P/files/:file_id/versions

folder_busy

When. The folder's subtree is being moved or copied by a background job.

What to do. Retry when the job is done.

Returned by. POST P/folders, PATCH P/folders/:folder_id, DELETE P/folders/:folder_id, POST P/folders/:folder_id/copy, POST P/uploads, PATCH P/files/:file_id, POST P/files/:file_id/versions

idempotency_key_reused

When. The Idempotency-Key was already used with a different request body.

What to do. Use a new key for a new request.

Returned by. POST P/uploads

name_conflict

When. A sibling with the same name exists in the folder (names are compared case-insensitively).

What to do. Choose another name.

Returned by. POST P/folders, PATCH P/folders/:folder_id, POST P/folders/:folder_id/copy, POST P/uploads, PATCH P/files/:file_id, POST P/files/:file_id/copy

scan_pending

When. The application blocks downloads until the malware scan is clean, and the scan has not finished.

What to do. Retry after file.ready, or poll the file until processing.scan is clean.

Returned by. GET P/files/:file_id/download, GET P/files/:file_id/content, GET P/files/:file_id/preview, POST /shares/:token/download

status_locked

When. The file is in review, approved or archived, and the change needs approve (or reopening it first).

What to do. Ask an approver, or move the file back to draft.

Returned by. PATCH P/files/:file_id, POST P/files/:file_id/versions, POST P/files/:file_id/versions/:version_no/restore

storage_account_in_use

When. The storage account still holds objects, is assigned to a tenant or takes part in a migration, so it cannot be removed or have its location changed.

What to do. Migrate the tenants off the account first; tenants and versions in the error say what still uses it.

Returned by. POST /platform/storage-accounts, PATCH /platform/storage-accounts/:storage_account_id, DELETE /platform/storage-accounts/:storage_account_id

storage_account_not_verified

When. The storage account failed its last verification, so no tenant can be assigned to it or migrated onto it.

What to do. Fix the account's settings or credentials and verify it again.

Returned by. PUT /platform/tenants/:tenant_id/storage-account, POST /platform/tenants/:tenant_id/storage-migrations

storage_migration_in_progress

When. A storage migration of this tenant is still running.

What to do. Wait for it to finish (follow it on its migration id), then retry.

Returned by. PUT /platform/tenants/:tenant_id/storage-account, POST /platform/tenants/:tenant_id/storage-migrations

upload_expired

When. The upload ticket's lifetime ended (1 hour single, 24 hours multipart).

What to do. Create a new ticket and upload again.

Returned by. POST P/uploads/:upload_id/parts, POST P/uploads/:upload_id/complete

upload_not_open

When. The ticket is already completed, being completed, or aborted.

What to do. Read the ticket with GET P/uploads/:upload_id; create a new one if needed.

Returned by. DELETE P/uploads/:upload_id, POST P/uploads/:upload_id/parts, POST P/uploads/:upload_id/complete

version_is_current

When. The current version cannot be deleted.

What to do. Restore another version first, or delete the file.

Returned by. DELETE P/files/:file_id/versions/:version_no

410 Gone

share_gone

When. The share link was revoked or expired, or its target was trashed or quarantined.

What to do. Ask for a new link.

Returned by. GET /shares/:token, POST /shares/:token/download

share_limit_reached

When. The share link reached its download limit.

What to do. Ask for a new link.

Returned by. POST /shares/:token/download

412 Precondition failed

revision_mismatch

When. The If-Match revision is stale: the item changed since it was read.

What to do. Read the item again and reapply the change.

Returned by. PATCH P/folders/:folder_id, PATCH P/files/:file_id, POST P/files/:file_id/versions

413 Payload too large

file_too_large

When. The declared size is above the application's max_file_size_bytes, the upload policy's, the tenant's or the platform cap.

What to do. Upload a smaller file; max_file_size_bytes is in GET P/settings/public.

Returned by. POST P/uploads, POST P/files/:file_id/versions

payload_too_large

When. The JSON body is larger than 256 KiB.

What to do. Send a smaller body. File bytes never go through the API: use an upload ticket.

quota_exceeded

When. The upload would exceed the application's or the tenant's quota; the body carries quota_bytes, used_bytes, reserved_bytes.

What to do. Free space (empty the trash, delete versions) or ask for a higher quota.

Returned by. POST P/uploads, POST P/files/:file_id/copy, POST P/files/:file_id/versions, POST P/files/:file_id/versions/:version_no/restore

422 Unprocessable

hash_mismatch

When. The stored object's SHA-256 differs from the declared content_sha256.

What to do. Upload the file again.

not_previewable

When. The item has nothing to preview.

What to do. Download it instead.

public_visibility_disabled

When. visibility: public was requested and the application (or the tenant) does not allow public files.

What to do. Use application or private, or enable public visibility in the settings.

Returned by. POST P/uploads, PATCH P/files/:file_id, PUT P/settings

share_links_disabled

When. Share links are switched off for the application or the tenant.

What to do. Enable them in the settings, or grant an access entry instead.

Returned by. POST P/folders/:folder_id/shares, POST P/files/:file_id/shares

size_mismatch

When. The stored object's size differs from the declared size. The object was deleted and the ticket failed.

What to do. Create a new ticket with the correct size.

Returned by. POST P/uploads/:upload_id/complete

storage_account_verification_failed

When. The write, read and delete probe against the storage account failed; nothing was saved.

What to do. Check the bucket, region, endpoint and credentials (or the directory) named in message, then retry.

Returned by. POST /platform/storage-accounts, PATCH /platform/storage-accounts/:storage_account_id

storage_adapter_not_allowed

When. This deployment cannot use the requested storage adapter or location (a directory outside the allowed roots, a directory account where the deployment does not allow one, an endpoint on a private or link-local address).

What to do. Use a bucket account, or a directory under one of the roots the operator allowed.

Returned by. POST /platform/storage-accounts, PATCH /platform/storage-accounts/:storage_account_id, PUT /platform/tenants/:tenant_id/storage-account, POST /platform/tenants/:tenant_id/storage-migrations

taxonomy_value_invalid

When. The application enforces its category or department list, and the value is not an active entry of it.

What to do. Pick a value from GET P/taxonomies/:name.

Returned by. POST P/uploads, PATCH P/files/:file_id

too_many_applications

When. The tenant has more applications than one tenant-level read or write handles.

What to do. Work per application.

Returned by. GET /tenants/:tenant_id/permissions, PUT /tenants/:tenant_id/permissions/roles/:role_id

too_many_entries

When. An item may carry at most 200 access entries of its own.

What to do. Use role or application entries, or grant on a parent folder.

Returned by. PUT P/folders/:folder_id/permissions, POST P/folders/:folder_id/permissions/entries, PUT P/files/:file_id/permissions, POST P/files/:file_id/permissions/entries

too_many_file_ids

When. More than 200 ids were sent in one batch.

What to do. Split the batch.

Returned by. POST P/files/urls, POST P/files/effective-permissions

too_many_scopes

When. The caller's access spans more than 5,000 permission scopes, too many for one search across the application.

What to do. Search within a folder (folder_id).

Returned by. GET P/search

type_not_allowed

When. The declared or detected type is outside the application's allowed_types (or the upload policy's).

What to do. Upload an allowed type; allowed_types is in GET P/settings/public.

Returned by. POST P/uploads, POST P/files/:file_id/versions

upload_incomplete

When. A multipart completion did not list every part, or a part is missing in the store.

What to do. Upload the missing parts (GET P/uploads/:upload_id lists what the store has) and complete again.

Returned by. POST P/uploads/:upload_id/complete

webhook_unreachable

When. The webhook URL did not answer the verification ping with a 2xx within 5 seconds.

What to do. Check the URL and that the endpoint answers ping events.

Returned by. PUT P/webhooks

429 Too many requests

rate_limited

When. Too many requests in the current window; retry_after (and the Retry-After header) says when to retry.

What to do. Wait retry_after seconds.

Returned by. Any authenticated route.

500 Server error

server_error

When. An unexpected error in the service.

What to do. Retry with backoff. If it persists, contact support with the timestamp and path of the response.

501 Not implemented

not_implemented

When. The route is planned (check-out, check-in, edit sessions) and not served yet.

What to do. Do not call it yet; it is listed with x-status: planned in the OpenAPI document.

Returned by. POST P/files/:file_id/checkout, DELETE P/files/:file_id/checkout, POST P/files/:file_id/checkin, POST P/files/:file_id/edit-sessions

503 Service unavailable

identity_unavailable

When. The service could not reach the Identity Server and has no fresh cached answer.

What to do. Retry with backoff.

Returned by. Any authenticated route.

storage_unavailable

When. The object store refused or did not answer; nothing was written.

What to do. Retry with backoff.

Returned by. POST P/uploads, GET P/uploads/:upload_id, POST P/uploads/:upload_id/complete, POST P/files/:file_id/versions