Timeline audio 400 codes: what each refusal means and the fix

Why did my timeline audio request fail with a 400? Sume refuses malformed requests with stable codes, so you can branch on the code rather than the message. The most common are audio_concat_requires_parts, audio_split_requires_ranges and audio_parts_channel_mismatch, all documented on the timeline audio page.

The endpoint is POST /v1/timeline-1.0/audio. It concatenates up to 20 parts or splits one file into up to 20 ranges, and costs a flat $0.01 per job.

Refusals and fixes

Concat and split take different fields, and mixing them is the main source of errors.

Source and host errors

unsupported_media_source and source_not_found mean an off-host or dead URL. Every URL must already be this workspace's media.sume.com audio, so a link such as https://example.com/a.wav is rejected at admit; import it first with POST /v1/media-imports.

Provider and ffmpeg keys such as filtergraph, ffmpeg_args, codec and crf return a 400. The server compiles the ffmpeg command itself, so you describe the outcome and never the command.

Limits behind the codes

Concat needs 1 to 20 parts, and split needs 1 to 20 ranges, which may overlap. Produced audio is at most 1,800 seconds. Output is wav by default and mp3 on request; keep WAV when the file will be joined again, because MP3 re-adds priming padding at each edge.

Each part may carry source_in and duration to trim it before the join.

Submit and poll

The Idempotency-Key header is required. The default mode is async; mode: "sync" waits up to 30 seconds for a 200 or returns 202 to poll. There is no GET for the audio resource itself, so poll GET /v1/jobs/:id/status and read GET /v1/jobs/:id/result, as set out in Sume jobs and results.

For more than 20 lines, join in two levels, as shown in joining more than 20 lines.

Handling the codes in code

Because the codes are stable, a client can map them to actions instead of showing a raw message. A reasonable map: the seven shape errors above are bugs in your request builder, so fail the build or the test; unsupported_media_source and source_not_found mean the media step was skipped, so run an import and retry once; and audio_parts_channel_mismatch means the inputs need normalising before a retry. None of these should be retried unchanged, since the same request will fail the same way.