keepcalculator

06 Numbers and Powers

Debug Malformed Multipart Form Data in a Speech API

Card No. 06·71422 · Updated · Standard formula, shown below

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

  1. Reproduce the error with verbose output. Use curl -v to see the full request and response headers. This shows the exact boundary and content-type the client sends, which is often the first clue.
  2. 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.
  3. Verify the Content-Type header. It must be multipart/form-data with a boundary parameter, like multipart/form-data; boundary=----WebKitFormBoundary7MA4YWxk. Missing or incorrect boundary is the most common cause of malformed errors.
  4. 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 --boundary at the start of each part) or trailing hyphens (the final delimiter is --boundary--).
  5. Inspect each part’s headers. Each part must have a Content-Disposition header with the correct field name, and for files, a filename parameter. For example: Content-Disposition: form-data; name="audio"; filename="sample.wav". Also ensure a blank line after the headers before the content.
  6. Confirm the file’s Content-Type. Some APIs expect a specific Content-Type for the audio part (e.g., audio/wav or audio/mpeg). If the API requires it, add a Content-Type header for that part. If not, omitting it is fine.
  7. 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.
  8. 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\n in the raw dump.
  9. 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.
  10. 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 audio or file). 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/post to 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 requests in Python or fetch with 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

The whole Numbers and Powers drawer →