Multipart Image Upload: A Practical Guide for Web, Mobile and Backend
Part 1: Understanding Chunked Multipart Upload
Part 2: Chunking the Image Locally
Part 3: Building the Multipart Upload API
Part 4: Making Uploads Reliable and Resumable (this post)
Part 5: Production Architecture and Cross-Platform Implementation
So far the upload works when nothing goes wrong. Phones don't give you that. They go into tunnels, flip between Wi-Fi and cellular, and get backgrounded by the OS mid-request.
Chunking already did the hard part: failures are now small and local. This post is about using that.
Retry only what failed
Five parts are uploading and one fails:
Part 1 ✓ Part 2 ✓ Part 3 ✗ Part 4 ✓ Part 5 ✓ With one big request the user would start over. Here only part 3 is retried. The other four are already on the server.
A retry policy that holds up:
- Retry network errors, timeouts and
5xxresponses. Don't retry4xx(the request is wrong, and sending it again won't fix that), except408and429. - Back off exponentially with jitter: roughly 1s, 2s, 4s, each with a random offset. Without jitter, clients that failed together retry together.
- Cap attempts per part at 3 to 5, then show an error and let the user try again.
async function sendWithRetry(send: () => Promise<Response>, max = 4) { for (let attempt = 1; ; attempt++) { let res: Response | undefined; try { res = await send(); } catch (e) { // network error or timeout: fall through to retry if (attempt >= max) throw e; } if (res?.ok) return res; if (res && res.status < 500 && res.status !== 408 && res.status !== 429) { throw new Error(`Part rejected with status ${res.status}`); } if (attempt >= max) throw new Error("Out of retries"); const delay = 2 ** (attempt - 1) * 1000 * (0.5 + Math.random()); await new Promise((r) => setTimeout(r, delay)); } } The status endpoint
Retrying blindly wastes requests. The client should be able to ask what the server actually has:
GET /api/uploads/abc-123/status { "uploadId": "abc-123", "totalParts": 5, "receivedParts": [1, 2, 4, 5], "missingParts": [3] } The server builds this from storage (which part files exist) or from a database row per part. The server is the source of truth. The client's own memory of what it sent can be wrong: a request may have succeeded while the response got lost on the way back.
Resume after a crash
The status endpoint pays for itself here. If the user force-quits the app halfway, or closes the tab, the flow on restart is:
Application crashes ↓ Application starts ↓ Load saved uploadId ↓ GET upload status ↓ Find missing parts ↓ Upload only the missing parts The client needs to persist very little: the uploadId and a way to find the file again (a path on mobile, a re-selected file on web). Everything else comes from the server. Local storage, shared preferences or a small database all work.
Check that the file hasn't changed before resuming. Compare size and modified time, or a hash saved at the start. If the user swapped the file, the old parts are useless and the upload restarts under a new uploadId.
Let sessions expire too. An upload nobody resumes should be cleaned up after, say, 24 hours. Part 5 covers that.
Idempotency: what if part 3 arrives twice?
Retries produce duplicates. The standard case: the client sends part 3, the server stores it, the response is lost. The client sees a timeout and sends part 3 again.
Client → Part 3 → Server (stored, response lost) Client → Part 3 → Server (again) The server shouldn't end up with part-3 and part-3-copy. It shouldn't reject the second request, and it shouldn't append the data twice. Sending it twice should have the same effect as sending it once.
That mostly falls out of the file naming from part 3. The storage location comes from partNumber, so the second write hits the same file. Writing to a temp file and moving it into place makes it safer:
Path target = partPath(uploadId, partNumber); Path temp = Files.createTempFile(target.getParent(), "part-", ".tmp"); chunk.transferTo(temp); Files.move( temp, target, StandardCopyOption.REPLACE_EXISTING, StandardCopyOption.ATOMIC_MOVE ); With the atomic move, a half-written part can't be mistaken for a finished one. If the process dies mid-write, you're left with a stray temp file for the cleanup job. You can also accept a SHA-256 header per part and verify it, so a corrupted chunk gets rejected and retried instead of stored.
Sequential or parallel
Sequential is the safe default:
1 → 2 → 3 → 4 → 5 Parallel can be a lot faster, because several requests share the bandwidth and hide per-request latency:
1 ────────┐ 2 ────────┤ 3 ────────┼──→ Server 4 ────────┤ 5 ────────┘ The protocol already allows it. Parts are independent and identified by number.
Why you need a concurrency limit
Firing all 50 requests at once is tempting, and it goes badly:
- Fifty streams share one link, so each is slow and more likely to time out.
- Browsers cap connections per host (typically 6 on HTTP/1.1), so most requests just sit in a queue.
- One user opening 50 connections looks like an attack on your own server.
- Phones pay for it in battery and memory.
Three or four at a time is usually about right. A small worker pool does it:
async function uploadAll(parts: number[], limit = 3) { const queue = [...parts]; const worker = async () => { while (queue.length > 0) { const partNumber = queue.shift()!; await sendWithRetry(() => sendPart(partNumber)); } }; await Promise.all(Array.from({ length: limit }, worker)); } Each worker takes the next part when it finishes one, so the pool stays full and never goes past limit. If a part runs out of retries, fail the run cleanly and let the user resume from status.
On mobile you might drop the limit on cellular, use smaller chunks on a weak signal, and pause when the connection drops.
The reliable loop
The whole client loop is short:
- Create the upload, or reload a saved one, to get the
uploadId. - Ask
/statusfor missing parts. - Upload those through a bounded pool, each with retry and backoff.
- Ask
/statusagain. If anything is still missing, go back to step 3. - Call
/complete.
Every step is safe to repeat, and that's what makes the thing hold up. Part 5 zooms out to production: components, per-platform clients, and the operational side.


