Mocking Multipart Validation Errors for File Upload Forms

Quick answer: A multipart request bundles text fields and file parts together, and validation can fail on any one of them, so mock each failure as a 400 or 422 that names the part at fault. This lets you test the inline error for a missing field, a wrong file type, or an oversized file without building real large uploads. The point is to confirm the client maps each error to the right input and keeps the rest of the form usable instead of showing one generic failure.

Why multipart validation is different

A JSON body is one document, but a multipart body is a sequence of parts separated by a boundary, where each part has its own name and a file part carries a filename and content type. A request can be rejected because a required text field is absent, a file has a type that is not allowed, a file exceeds the size limit, or one file among several is bad. The server has to say which part failed, and the client has to place that message on the correct input. Triggering these against a real backend means crafting large or malformed files and waiting on slow uploads, which makes the error paths tedious and easy to skip.

Mock the failure per part

Use response overrides for each validation branch and match on whether a part is present, its declared type, or its filename. Every mocked error should name the field or file so the client can locate it. The cases below cover the distinct branches.

The multi-file row matters because a naive client clears the whole list when one item fails. The mock should prove only the bad file is flagged and the others remain.

How the client should map the errors

Read the part name from the error and render the message at that input rather than opening a generic alert. Keep the already-filled fields and valid files in place, so a single failure does not force the user to start over. For an oversized file, show the limit and block that file without discarding the rest of the form, and confirm the client does not send the same rejected upload in a blind retry loop. Check the recorded requests to see the parts the mock actually received and confirm the error mapping. A desktop API workspace lets you define these multipart overrides, inspect the recorded parts, and assert on the error fields in the same place. Powerduck works this way, so each upload failure is a fixed response rather than a hard-to-stage file.

Honest limits

A local mock runs in the desktop main process and does not replace the real backend, so the limits and type rules are ones you define. The mock does not store files, run malware scans, or process images, and it does not prove the live server's size cap, type whitelist, or chunked-upload behavior. Real network interruptions, upload timeouts, and the actual rejection status should be confirmed with a small set of genuine uploads. Importing a schema does not deploy a backend, and a passing mock run is not evidence about the upstream service.

Frequently asked questions

Is a multipart error always a 400? Not always. Depending on the rule, a server may return 400, 413, 415, or 422. Mock the status your API actually uses for each branch and keep the part name in the body.

How do I test an oversized file without making one? Mock the size-limit response instead of uploading a real large file. The client's size message and its no-retry behavior are what the test proves.

When several files upload, should one failure clear them all? No. The error should identify the bad file by index and leave the valid files in place, so the user only fixes what failed.

Does the mock validate the real file content? No. It matches the request by part and returns the branch you configured. Confirm real content checks and scanning separately against the live service.

The bottom line

Treat multipart validation as a set of per-part failures, not one generic error, and mock each branch with the part named so the client can place the message correctly. Cover missing fields, wrong types, size limits, and the multi-file case, keep valid inputs on failure, and verify the real upload rules separately. For more on this approach, see the API mocking guide hub.