Troubleshoot Storage

First confirm TARUVI_SITE_URL, the app slug, the bucket slug, and the file path, and that file URLs end with a trailing slash.

Upload and object validation (400)

Message or symptom	Typical cause	What to do
File size exceeds bucket limit	File larger than the bucket's file_size_limit (default 50 MB)	Use a smaller file, or raise the bucket limit with PATCH (up to 5 GB)
MIME type not allowed	allowed_mime_types rejects derived type	Upload a matching type or widen the list on the bucket
Cannot upload empty file	Zero-byte body	Upload non-empty content
Metadata size exceeds S3 limit of 2KB	Metadata JSON too large	Shrink or remove metadata keys
Path is required	No path or filename on POST /objects/	Add a path form field, or upload with PUT /objects/{key}/
Object key is required for raw binary uploads	Raw bytes sent without a path in the URL	Use PUT /objects/{key}/ with a Content-Type header

Bucket create or update (400)

Message or symptom	Typical cause	What to do
App category field is required	Missing app_category on create	Send assets or attachments — see Security and limits
storage_provider is immutable	PATCH tried to change provider	Create a new bucket; files can't be copied or moved between providers
Bucket slug already exists	Duplicate slug in the same app	Pick another name (slug is derived from name)
Quota must be ≥ file size limit	max_size_bytes below file_size_limit	Raise quota or lower per-file limit
File size limit exceeds platform maximum	file_size_limit above 5 GB	Set it to 5 GB or less
Slug unchanged after rename	slug is read-only	Update name only; slug does not change via API

Access (403)

Symptom	Typical cause	What to do
Bucket POST / PATCH / DELETE denied	The caller isn't an organization owner or admin, or a cloud user with access to the site	Use an API key generated by such a user
Object read, write, delete, copy, move denied	The bucket's access policy doesn't allow it	Grant the action for the caller's role — see Access policies
Edit URL denied on public object	Edit never bypasses auth	Authenticate; caller needs update on the bucket
Browse denied anonymously	Browse requires auth even for public buckets	Authenticate, or use filtered GET /objects/ for public reads

Default policies: assets is read-only for typical roles; attachments allows read/create/update; delete is not in either default.

Not found (404)

Symptom	Typical cause	What to do
Object not found in storage	The file's record exists but its content is missing from the provider	Upload the file again; if it keeps happening, contact support
Object not found	Wrong path, or the URL has no trailing slash	Paths are case-sensitive and include folders — check with browse or list using prefix

Copy and move

Symptom	Typical cause	What to do
Cross-provider move is not supported	Source and destination providers differ	Download the file, upload it to the other bucket, then delete the original
Object already exists at destination (409)	Path taken	Delete, rename, or pick another path
Source object not found	Bad source_path or app scope	Confirm path under the URL's app_slug

SharePoint provider codes

Provider code	Meaning	What to do
sharepoint_site_not_ready	SharePoint isn't set up for this site yet	Wait a few minutes and retry; if it persists, contact support
non_office_edit_rejected	Non-Office MIME on edit URL	Download, edit locally, re-upload
path_too_long	URL exceeds SharePoint limit	Shorten path segments
guest_invite_rejected	The email belongs to your own Microsoft organization, so it can't be invited as a guest	Use an external email address, or add the user to your Microsoft organization
guest_invitation_propagation_timeout	SharePoint took longer than 8 seconds to grant access	Retry the request
graph_api_error	Microsoft Graph failure	Use graph_code, retry_after, and request_id from the error

Batch operations

Symptom	Typical cause	What to do
207 Multi-Status on batch delete/upload	Partial failure	Fix each failed[] entry; retries are per path, not whole batch
Total file size exceeds 800MB	Batch over cap	Split into smaller batches
Paths must be unique	Duplicate paths in one batch	Deduplicate paths

Batch limits: up to 100 items per request. Upload rejects the whole request when total size exceeds 800 MB or paths duplicate.

Quotas and usage

Bucket max_size_bytes and max_objects are checked periodically, not on every upload, so going over a quota doesn't block uploads. GET .../usage/ shows usage as of the last recalculation.