This guide walks you through diagnosing and fixing malformed multipart/form-data requests when uploading audio to a speech recognition API. You’ll learn what causes these errors, how to inspect the raw request, and the exact steps to correct the payload so the API accepts your file.
What You’ll Need
- A tool to inspect HTTP requests:
curl, Postman, or a browser’s developer tools (Network tab) - Access to the API’s documentation (to verify field names, file field, and content types)
- A sample audio file (e.g., WAV or MP3) that reproduces the issue
- Basic familiarity with command line or your chosen HTTP client
Step-by-Step
- Reproduce the error with verbose output. Use
curl -vto see the full request and response headers. This shows the exact boundary and content-type the client sends, which is often the first clue. - Capture the raw request body. Save the exact payload being sent. With curl, add
--trace-ascii -or--trace -to dump the entire request, including binary audio data. In Postman, use the console (View > Show Postman Console) to see the raw request. - Verify the Content-Type header. It must be
multipart/form-datawith a boundary parameter, likemultipart/form-data; boundary=----WebKitFormBoundary7MA4YWxk. Missing or incorrect boundary is the most common cause of malformed errors. - Check the boundary string consistency. The boundary in the Content-Type header must exactly match the delimiter lines in the body. Look for missing leading hyphens (should be
--boundaryat the start of each part) or trailing hyphens (the final delimiter is--boundary--). - Inspect each part’s headers. Each part must have a
Content-Dispositionheader with the correct field name, and for files, afilenameparameter. For example:Content-Disposition: form-data; name="audio"; filename="sample.wav". Also ensure a blank line after the headers before the content. - Confirm the file’s Content-Type. Some APIs expect a specific Content-Type for the audio part (e.g.,
audio/wavoraudio/mpeg). If the API requires it, add aContent-Typeheader for that part. If not, omitting it is fine. - Validate the audio data is not corrupted. The file itself must be a valid audio file in the format the API expects. Test with a known-good file. If the file is empty or truncated, the API may reject the entire request.
- Check for extra or missing CRLF characters. Each part ends with a CRLF, and the final boundary is followed by a CRLF. Some clients use LF only, which can break strict parsers. Look for
\r\nin the raw dump. - Try a minimal request. Use curl with just the file field and no other parameters to isolate the issue. If that works, add fields one by one to find the culprit.
- Compare with a working example. If you have a working request (from the API docs or a previous success), diff the raw bodies to spot the difference.
Common Mistakes
- Using the wrong field name. The API expects a specific field (like
audioorfile). Check the docs. A mismatch often results in a malformed error if the parser can’t find the file part. - Forgetting the filename parameter. Some APIs require a filename in the Content-Disposition. Without it, the part may be treated as a text field.
- Setting the Content-Type to application/json. If you set the header manually and forget the boundary, the server won’t parse it as multipart.
- Using a non-ASCII filename. Some servers struggle with special characters. Use a simple ASCII filename like
audio.wav. - Not closing the request properly. The final boundary must have two trailing hyphens (
--boundary--). A missing final delimiter leaves the server waiting for more data.
Tips
- Use a tool like
httpbin.org/postto test your multipart construction. It echoes back what it received, helping you see if the structure is correct. - In curl, use
-F "audio=@file.wav;type=audio/wav"to set the part’s Content-Type explicitly. - If you’re writing code, use a well-tested library (like
requestsin Python orfetchwith FormData in JavaScript) instead of hand-building the payload. Libraries handle boundaries and headers correctly. - Enable API logging if available. Many speech services log the request size and headers, which can help confirm what the server received.
- Keep your audio file small (a few seconds) while testing to reduce noise in the raw dump.
Troubleshooting
If the error persists after checking all steps:
- Try a different client. If you’re using a custom script, test with curl or Postman. If curl works, the issue is in your code’s request construction.
- Check the API’s error message. Some APIs return a more specific message like “missing audio field” or “invalid boundary”. Use that to narrow down the issue.
- Verify the audio format. The API may reject a file with the wrong extension or MIME type. Convert your file to a standard format (e.g., WAV 16kHz mono) and try again.
- Look at the server’s response headers. A 400 Bad Request with a body explaining the issue is common. Read the response body carefully.
- If using a proxy or load balancer, ensure it doesn’t modify the Content-Type or strip the boundary. Test by hitting the API directly.
- As a last resort, use a network sniffer like Wireshark to capture the exact bytes sent. Compare with a known-good request.
Frequently Asked Questions
Why does my multipart request work in Postman but not in my code?
Postman automatically sets the boundary and headers. Your code may be missing the boundary parameter or using a different line ending. Compare the raw requests.
What does “malformed multipart/form-data” mean exactly?
It means the server couldn’t parse the request body as valid multipart. This is usually due to a missing or inconsistent boundary, missing part headers, or incorrect line breaks.
Can I send the audio as a base64 string instead?
Some speech APIs support raw JSON with base64 audio. Check your API’s docs. If it does, that’s often simpler and avoids multipart issues.
How do I set the boundary manually in curl?
Use -H "Content-Type: multipart/form-data; boundary=myboundary" and then manually format the body with --data-binary. But it’s easier to let curl handle it with -F.
Is there a size limit for the audio file?
Most APIs have a limit (e.g., 10MB or 100MB). If your file is too large, the request may be rejected. Check the docs. If the file is huge, consider chunked uploads or compression.
Why does the API say “no audio data found” even though I attached a file?
This usually means the file part is missing or the field name is wrong. Double-check the Content-Disposition header and the field name in your request.
Related
Method: the standard formula for this calculation, rounded as each result states. See how the calculators work or report an error.
More cards in this drawer
- Tongue Escape Codes: What They Are0.20 movements/s
- Claude Code Workflow Habits Worth Trying
- HDMI 2.1 Explained: Why It Matters for Gaming
- Veeam Plugin for VMware Cloud Director: How It Works
- Best Path of Titans Server Hosting: Top Picks
- Oppo First Foldable: 120Hz Display & Snapdragon 888