Enter a keyword to search published documentation.
mywebdrive
Uploads and Recovery
The four stages of an upload—intent, parts, completion, finalization—plus retries, replacement, and what to do when things go wrong.
Four stages of an upload
- Core creates an Upload Intent, reserves quota, and returns the intent, objectKey, and uploadGrant.
- The browser transfers sequential 5 MiB parts (5 × 1024 × 1024 bytes) to Storage.
- The browser submits the part count. Storage queues assembly and finalization for its Worker.
- The Worker checks the object and calls Core. Core commits the version and quota accounting; a usable version then appears in the list.
The progress bar measures transferred parts, not background finalization. The page polls at most 20 times with roughly 500 ms between attempts. Exceeding that observation window produces a processing message, not proof of final failure. Polling checks only the first 100 files and matches by filename. For strict verification, inspect the version and size and compare downloaded contents.
File and authorization limits
Use a nonempty file. Its trimmed name must contain 1–255 characters and no slash, backslash, or control characters. MIME type must also be nonempty. API sizeBytes is a positive decimal integer string, not a floating-point number or a value with units.
An Upload Intent lasts 15 minutes; uploadGrant lasts at most 300 seconds. These are different deadlines. A slow large transfer can lose authorization before the intent expires. The current browser offers no transparent grant renewal or resume-across-refresh guarantee. 5 MiB is the part size, not a whole-file limit. Available quota, authorization lifetime, and deployment boundaries also constrain uploads.
API sequence and retries
Create with POST /api/v1/upload-intents and Idempotency-Key. The JSON contains fileName, string sizeBytes, mimeType, and optional parentId. Send parts with PUT /api/v1/storage/uploads/{objectKey}/parts/{partNumber}, starting at 1. Storage requests use uploadGrant, not the login access token. Complete with POST /api/v1/storage/uploads/{objectKey}/complete and a JSON object whose numeric parts field is the total part count.
Retry the same logical request with the same key and identical parameters. Reusing a key for different data conflicts; generating a new key for every uncertain retry can reserve space repeatedly. Never call /api/v1/internal/* finalization callbacks from a client—those are private service protocols.
Identify the failed stage
| State | What to do next |
|---|---|
| Intent creation failed | Check parameters, identity, and quota; no transfer authorization exists yet |
| Part transfer failed before completion submission | The page attempts cancellation and reports a cancellation failure separately |
| Completion submitted but file absent | Wait, refresh, and inspect file/version state before submitting again |
| 409 | Check name, idempotency key, target file, and intent state |
| 413 | Check declared size and allowed byte boundaries; repeated retries alone won't help |
| 401 | Check grant type and lifetime; signing in again doesn't renew an old grant |
POST /api/v1/upload-intents/{id}/cancel cancels an active intent, returning 204. An intent that can no longer be cancelled may return 409. Cancellation doesn't delete a completed file.
Replace an existing file
POST /api/v1/files/{fileId}/upload-intents creates a replacement intent. Transfer and finalization follow the same sequence. The current upload panel only creates new uploads; it has no replacement selector. A new-upload name conflict isn't automatic overwrite. Replacement retains the logical file and adds a version; see Quota for its accounting.