Start with the error field of the answer: it is a stable code, and the error catalog says what each one means and what to do. This page groups the problems people meet most, by symptom. It is for backend developers, administrators and Identity Server operators.
| Symptom |
Check |
invalid_token on every call |
The token’s aud is files-api: request it with resource=https://files.centralcodestation.com/api, the identifier, not the audience. A token for your own API, Chat or Notifications never works here. An expired token is renewed by the Node client on its own |
invalid_target from the Identity Server |
resource is the identifier; your client has a resource permission (or a token-exchange row) for the Files API; Files is on for the application |
insufficient_scope |
A machine token needs files:manage, files:read or files:config.manage, and some routes need a specific one: settings need files:config.manage, writes need files:manage |
client_context_mismatch |
Your client belongs to another tenant or application than the one in the URL. A tenant application’s client works only in its own context |
files_access_not_granted |
Files is switched off for the application at the Identity Server (Applications, your application, Platform Apps) |
principal_not_allowed |
A user-only route called with a machine token (the role matrix), or a machine-only route with a user token (effective permissions of another user) |
503 identity_unavailable |
The Identity Server is unreachable; retry with a back-off |
| Symptom |
Check |
type_not_allowed at the ticket |
The declared mime_type is outside the application’s allowed_types or the upload policy’s. Read them with GET P/settings/public |
The file was accepted, then trashed by system |
Processing detected another type than declared (type_mismatch_policy: reject), a type outside the list, or a checksum mismatch. The file.failed event and the audit row file.rejected say which |
file_too_large or quota_exceeded |
The application’s size or quota, or the tenant’s. The quota error carries the numbers; see Quota and retention |
| The PUT answers 403 |
The URL expired (single PUT tickets live 1 hour, part URLs 1 hour), or the request carried a header the URL is not signed for: send exactly the ticket’s headers, no Authorization, and the declared Content-Type |
size_mismatch at completion |
The bytes sent differ from the declared size. The object was deleted: create a new ticket |
upload_incomplete |
A multipart completion did not list every part with its ETag (keep the quotes the store returns) |
upload_expired or upload_not_open |
The ticket ended, or was already completed or aborted. A second completion after a lost answer: read the file instead |
name_conflict |
A sibling has the same name, ignoring case. Send on_name_conflict: "rename" or another name |
tenant_suspended |
A platform administrator paused uploads for the tenant. Reads keep working |
The app cannot read ETag from a part PUT |
Read the response header ETag exactly; part PUTs need no request headers |
| Symptom |
Check |
rendition_not_available |
The rendition is not ready yet (pending), was not made for this file (skipped, with the reason in error), or the kind has none (videos have no preview; Office documents have no rendition). Mint the original inline meanwhile |
processing.renditions stays pending |
Processing runs in the background and normally finishes within seconds; a large video takes longer. GET P/files/:file_id/renditions shows each rendition’s status and error; POST P/files/:file_id/renditions runs them again |
file_pending |
The upload was never completed |
scan_pending |
The application waits for the malware scan; retry after file.ready. When the message names scan_failed_policy or scan_oversize_policy, the file will not be served under the current settings. See Malware scanning |
file_quarantined |
The scan found malware. The file is never served; purge it and tell the owner |
A video has no mp4_1080p |
The source is not larger than 720p (error: source_smaller). Longer or larger videos get no MP4 renditions and play from the original; see Previews and renditions |
file_trashed |
The file is in the trash; restore it or drop it from your record |
file_on_hold on purge or version deletion |
The file is under a legal hold; the body carries the hold’s reason, who placed it and its end. Someone with files.manage releases it, or wait for its until |
| A URL stopped working |
Signed URLs expire (default 15 minutes). Mint again; never store them |
A preview answers kind: none |
Nothing displayable exists: an image format browsers cannot show and no rendition yet, an Office document (there is no Office preview), an archive, a quarantined file. Offer a download |
| Symptom |
Check |
file_not_found for a file that exists |
The user may not view it: the service never says “exists but forbidden”. Ask GET P/files/:file_id/effective-permissions from your backend to see the user’s actions and via |
missing_action |
The user sees the file but lacks the action. Check the owner actions, the entries on its folders and whether a folder breaks inheritance |
missing_capability |
A system-level key is needed (settings, audit, the role matrix): the tenant owner grants it on the Permissions page |
cannot_grant_more_than_held |
An entry names actions the granter does not hold on the item |
partial_permission |
Trashing a folder is blocked by descendants the caller may not delete; blocked lists them |
too_many_scopes on search |
The user’s access spans too many separate folders: add folder_id |
folder_managed |
The item is in an application-managed folder (managed_folder_id names it): people cannot change it, whatever my_actions lists. Make the change from the application’s backend; share links are refused there for everyone |
principal_not_allowed when creating or updating a folder |
A user token sent managed: only a backend client with files:manage marks or unmarks a folder |
| Symptom |
Check |
| A folder or file is read-only in the console, with Managed by |
An application manages it (Application-managed folders). Change it through that application; in an emergency the tenant owner releases the folder |
| The Permissions page is read-only |
Only the tenant owner and holders of files.permissions.manage may change it; only the owner may grant files.permissions.manage itself (tenant_owner_required) |
A settings change is refused with invalid_request |
message lists every value outside its range; see Settings |
public_visibility_disabled or share_links_disabled |
The application’s setting, or the tenant’s ceiling set by a platform administrator |
platform_admin_required |
Platform administration needs the Identity Server’s platform administrator role, or a machine client of the Files platform application itself; a tenant’s own client never passes |
storage_account_verification_failed |
The probe of a new or changed storage account failed; the message is the store’s own error (wrong keys, bucket, region or endpoint). See Storage accounts |
storage_unavailable |
The storage that holds the file cannot be reached right now; retry later |
| Symptom |
Check |
webhook_unreachable when saving |
The service pings the URL first and saves only on a 2xx in time; the message says what it got. Deploy the receiver before you save |
webhook_url_not_allowed |
The URL must be https, carry no credentials, and point to a public address |
Deliveries stopped, disabled_at is set |
The webhook was switched off after repeated failed events; fix the endpoint and save the webhook again. See Webhooks |
| The same event arrives twice |
Delivery is at least once: de-duplicate on the body’s id |