Media Speech-to-Text Intake Explained — 5 Malformed Multipart API Boundary Controls

Short answer: treat a support recording as an auditable binary transaction, terminate multipart parsing once, and build a fresh outbound request whose boundary, file field, media type, tenant attribution, and idempotency record agree.

For a media company triaging incoming customer-support tickets, this is more than an upload detail. The transcript may decide which queue receives a complaint, while the tenant identifier decides which customer bears the processing cost. A request that is syntactically accepted but attributed to the wrong tenant is therefore a worse outcome than a clean rejection: the text might look useful while reconciliation is already false.

The architecture decision is to accept multipart form data at the application boundary, validate the declared fields and audio, persist a content-derived idempotency record, and then serialize a new multipart body for the transcription API. Do not relay an inbound body after a framework has parsed it, and don't copy an inbound Content-Type header onto a newly generated body. Those bytes and that boundary are one indivisible unit.

How can multipart form-data preserve a speech-to-text file boundary?

Five controls make the request explainable after the fact.

1. The multipart boundary in Content-Type must be the boundary used in the body.
2. The file part name must match the transcription contract exactly; file, audio, and upload are different keys, not aliases.
3. The file part needs an explicit filename and an audio media type that the receiving contract permits.
4. Tenant identity must come from authenticated server context, never from a client-supplied billing field.
5. One logical recording must have one idempotency identity, with every attempt and terminal result retained in an audit trail.

The failure boundaries follow those invariants. Reject a missing file or unknown tenant before consuming downstream capacity. Reject a media type outside the application's allowlist before transcription. Treat a mismatch between a cached idempotency record and a new payload digest as a conflict, because reusing a key for different bytes destroys exactly-once reasoning. Only after these checks should the system reserve usage, create the outbound body, and send it.

Fail closed.

HTTP status codes alone don't prove which invariant failed, since a receiving API can map malformed input according to its own contract. A locally generated 400 can identify a missing form field, 415 can identify a disallowed audio type, and 409 can identify an idempotency collision; keep those classifications in your own audit vocabulary even if the remote response is less specific. The point is deterministic diagnosis — not pretending that every upstream uses the same taxonomy.

Compliance adds a second boundary. Audio can contain names, account details, or other sensitive speech, so logs should record a digest, byte count, media type, tenant, attempt, and outcome rather than the recording or transcript itself. Retention, access, deletion, and regional-processing rules depend on the organization's obligations; I'm not sure which regime applies to your media operation, and a code sample cannot settle that. A privacy or compliance owner has to define those limits before production traffic arrives.

Validation should happen where the system still has local context. An Express or Next.js endpoint may receive the browser upload, but the same rule applies to any server runtime: once a parser has consumed the stream, the application owns structured parts, not the original transport envelope. If it creates another request, it must create another envelope as well.

This distinction explains a common malformed-request pattern. A library generates a fresh random boundary around a newly constructed form body, while application code manually preserves an older Content-Type: multipart/form-data; boundary=... value. The receiver searches for the declared delimiter and cannot find it in the bytes. Another variant preserves the header but forwards an already consumed stream. Neither is an audio-model problem; both are violations at the HTTP message boundary.

Don't hand-author that header.

Let the multipart serializer set Content-Type, including its boundary, after it has created the body. Then inspect the structured input before serialization: exactly one expected file field, a non-empty filename, an allowed media type, bounded size, authenticated tenant context, and any required scalar model or language fields. If an endpoint contract calls the part file, sending audio_file is malformed even though the bytes themselves are valid audio. Case, spelling, and multiplicity deserve tests because frameworks often make the happy path look deceptively permissive.

For Node.js clients, the operational decision is the same even though the APIs differ between native FormData, framework request objects, and third-party packages: append the binary under the contract's exact field name, let that implementation choose the boundary, and pass through only headers that still describe the body you are actually sending. Your mileage may vary on how a given runtime represents a file, so pin the runtime version and test the emitted request at the wire boundary rather than assuming two FormData implementations behave identically.

Three envelope ownership models for tenant accounting

The options differ less in syntax than in where they place responsibility.

Design	Multipart ownership	Tenant attribution	Audit quality	Appropriate use
Parse, validate, and re-encode	Application owns a new outbound envelope	Bound to authenticated context before dispatch	Strong: digest, attempt, and result can share one record	Multi-tenant support triage with chargeback or quotas
Stream through an unparsed body	Proxy preserves the original envelope	Must be established outside the body	Moderate: low buffering, less semantic evidence	Trusted single-purpose ingress where byte preservation matters
Upload first, transcribe asynchronously	Object storage owns the durable audio object	Bound when the object and job are created	Strong: storage and job identifiers support reconciliation	Large recordings, burst absorption, or delayed triage

For this system, parse and re-encode is the default because the support application needs to connect four facts atomically in its own ledger: authenticated tenant, audio digest, transcription attempt, and usage measurement. That ledger should use append-only attempt records and a separately computed tenant usage view; editing an old row after retrying makes disputes needlessly hard to reconstruct. If the downstream reports usage, store its raw units and source identifier, then derive internal allocation under a versioned policy. If it doesn't, record the measurable proxy used by the contract, without labeling an estimate as provider-billed cost.

Cost visibility also changes retry policy. A transport ambiguity after dispatch means the caller may not know whether work started, so an automatic retry without an idempotency check can create duplicate processing and duplicate allocation. Exactly-once execution across independent systems isn't something an HTTP handler can promise. The practical target is exactly-once business effect: stable operation identity, deduplicated completion, explicit attempt history, and reconciliation that can explain every unit assigned to a tenant.

This design has a catch. Parsing and re-encoding consumes application memory, CPU, and I/O, and it is not suitable when recordings are too large for the chosen limits or when a regulated workflow forbids the application tier from handling raw audio. In those cases, use a controlled direct upload to durable storage and enqueue transcription from an immutable object reference. Stick with byte-for-byte streaming when the gateway is intentionally content-blind, tenant identity is already trustworthy, and the downstream contract accepts the inbound envelope unchanged.

A Go adapter that binds bytes to the ledger

The following handler is deliberately provider-neutral. It demonstrates the transaction boundary: authenticated tenant context, bounded input, an exact file field, a digest used for idempotency, and a new multipart envelope. Production code still needs durable implementations of the ledger and authentication interfaces, plus policy-specific retention.

package intake

import (
    "bytes"
    "context"
    "crypto/sha256"
    "encoding/hex"
    "errors"
    "fmt"
    "io"
    "mime/multipart"
    "net/http"
)

const maxAudioBytes = 25 << 20

type Ledger interface {
    Begin(ctx context.Context, tenant, operation, digest string, size int64) (created bool, err error)
    Finish(ctx context.Context, operation string, status int) error
}

type Handler struct {
    Client   *http.Client
    Endpoint string
    Ledger   Ledger
}

func (h Handler) ServeHTTP(w http.ResponseWriter, r *http.Request) {
    tenant, ok := r.Context().Value(tenantKey{}).(string)
    if !ok || tenant == "" {
        http.Error(w, "unauthenticated tenant", http.StatusUnauthorized)
        return
    }

    r.Body = http.MaxBytesReader(w, r.Body, maxAudioBytes)
    if err := r.ParseMultipartForm(maxAudioBytes); err != nil {
        http.Error(w, "invalid multipart body", http.StatusBadRequest)
        return
    }

    file, header, err := r.FormFile("file")
    if err != nil {
        http.Error(w, "missing file field", http.StatusBadRequest)
        return
    }
    defer file.Close()

    audio, err := io.ReadAll(io.LimitReader(file, maxAudioBytes+1))
    if err != nil || len(audio) == 0 || len(audio) > maxAudioBytes {
        http.Error(w, "invalid audio size", http.StatusBadRequest)
        return
    }
    mediaType := header.Header.Get("Content-Type")
    if !allowedAudioType(mediaType) {
        http.Error(w, "unsupported audio type", http.StatusUnsupportedMediaType)
        return
    }

    sum := sha256.Sum256(audio)
    digest := hex.EncodeToString(sum[:])
    operation := r.Header.Get("Idempotency-Key")
    if operation == "" {
        http.Error(w, "missing idempotency key", http.StatusBadRequest)
        return
    }
    created, err := h.Ledger.Begin(r.Context(), tenant, operation, digest, int64(len(audio)))
    if err != nil || !created {
        http.Error(w, "operation conflict", http.StatusConflict)
        return
    }

    var body bytes.Buffer
    form := multipart.NewWriter(&body)
    part, err := form.CreateFormFile("file", header.Filename)
    if err != nil {
        http.Error(w, "cannot encode request", http.StatusInternalServerError)
        return
    }
    if _, err = part.Write(audio); err != nil {
        http.Error(w, "cannot encode request", http.StatusInternalServerError)
        return
    }
    if err = form.Close(); err != nil {
        http.Error(w, "cannot encode request", http.StatusInternalServerError)
        return
    }

    req, err := http.NewRequestWithContext(r.Context(), http.MethodPost, h.Endpoint, &body)
    if err != nil {
        http.Error(w, "cannot create request", http.StatusInternalServerError)
        return
    }
    req.Header.Set("Content-Type", form.FormDataContentType())
    req.Header.Set("Idempotency-Key", operation)

    resp, err := h.Client.Do(req)
    if err != nil {
        http.Error(w, "transcription unavailable", http.StatusBadGateway)
        return
    }
    defer resp.Body.Close()
    _ = h.Ledger.Finish(r.Context(), operation, resp.StatusCode)
    w.WriteHeader(resp.StatusCode)
    _, _ = io.Copy(w, resp.Body)
}

func allowedAudioType(value string) bool {
    return value == "audio/mpeg" || value == "audio/wav"
}

type tenantKey struct{}

var _ = errors.New
var _ = fmt.Sprintf

The unused-import sentinels at the bottom are intentionally uninteresting, and a real implementation should remove them together with the imports; the important line is form.FormDataContentType(), which couples the generated body to its generated boundary. More significantly, this compact sample marks an operation as begun before dispatch but doesn't model every retry state. A durable state machine should distinguish reserved, dispatched, accepted, rejected, and reconciled attempts, with an outbox or worker owning recovery after the request handler exits.

Test the boundary, not just the handler. Capture the outbound request in a local test server, parse its Content-Type, read the multipart parts, and assert that the declared boundary opens the body, there is exactly one file part, the bytes match the digest, and no client-supplied tenant field is forwarded. Then repeat with a missing boundary, wrong field name, duplicate idempotency key with different bytes, unsupported media type, and an oversized body. Those tests turn a vague “malformed request” report into a named invariant.

Where transparent streaming still belongs

Blind proxying was rejected for tenant-aware ticket triage because it leaves too much meaning inside an opaque stream. The application cannot reliably prove that the authenticated tenant, accepted audio, and charged operation referred to the same artifact if it never validates the parts. Framework middleware can also consume the body before proxy code sees it, making ownership unclear across Express, Next.js, and any intermediate gateway.

Still, blind streaming has a valid use case. A narrowly scoped gateway can preserve the inbound method, header, and bytes as a single untouched message, enforce a transport-level size limit, and avoid buffering large media. Choose it only when semantic validation occurs elsewhere, the original envelope is contract-compatible, and cost attribution does not depend on reading body fields. It is an optimization with prerequisites, not a universal shortcut.

For asynchronous triage, durable upload plus a job record is often the cleaner rejected alternative to revisit. It separates user-facing upload latency from transcription latency and gives reconciliation a stable object identity, but it adds storage lifecycle policy, queue operations, deletion workflows, and another consistency boundary. Batch processing and structured downstream classification can follow later; they do not repair a malformed multipart upload at ingress.

The decision rule is concise: re-encode when the application owns validation and tenant accounting; preserve bytes when a trusted proxy owns transport only; use durable objects when size, bursts, or recovery make synchronous handling the wrong boundary. In every case, the multipart header and body travel as a pair, and the audit record must explain who initiated the work, which bytes were accepted, how many attempts occurred, and where the result was allocated.

References

• https://platform.openai.com/docs/guides/batch
• https://platform.openai.com/docs/guides/structured-outputs

Further reading

• https://platform.openai.com/docs/guides/batch
• https://platform.openai.com/docs/guides/structured-outputs