docs/API_ERRORS_AND_PARAMETER_VALIDATION.md

API errors and parameter validation

Last updated: 2026-05-12

Purpose

Failed extraction requests must be visible in the application UI. Users should not need to open the browser network monitor to understand why a job did not start.

Implemented behavior

• POST /api/jobs now accepts browser-form-style parameter values for numeric and boolean fields.
  • Example: the MIDI grid selector sends "16"; the backend coerces it to integer 16 before validation.
  • Integer fields: demucs_shifts, target_min, target_max, subdivision.
  • Float fields: Demucs overlap, onset, duration, clustering, and threshold controls.
  • Boolean fields: synthesize, quantize_midi, use_disk_cache.
• Invalid request bodies return actionable 400 errors prefixed with Invalid extraction parameter: or Invalid params JSON:.
• The frontend has a global visible error banner for failed API/network requests.
• Pipeline runtime errors also surface in the banner and remain available in the Pipeline panel logs.
• The extraction start path writes failed-request details into resultSummary and logs so the error is visible even if the banner is dismissed.

Regression fixed

The UI sent the subdivision selector value as a string. The backend previously validated it directly against {4, 8, 16, 32, 64}, so "16" failed with:

{"detail":"subdivision must be one of 4, 8, 16, 32, 64"}

That is now fixed in both places:

1. web/app.js converts controls based on the /api/config default parameter types.
2. pipeline_runner.PipelineParams.from_mapping() coerces JSON/form values defensively before validation.

Validation

Run:

python3 scripts/test_param_validation_and_api_errors.py

This verifies:

• browser-style string values are accepted and coerced;
• invalid subdivisions still fail;
• /api/jobs accepts a string subdivision from the UI;
• bad parameter responses include visible actionable details.

Upload/runtime fallback update (2026-05-12)

• Added a visible top-bar Choose audio affordance in addition to whole-app drag/drop.
• Fixed the default hidden state of the error banner so placeholder errors are not shown on page load.
• API errors now surface request path/status/detail in the visible banner and pipeline logs.
• /api/config now includes runtime diagnostics for optional separation backends.
• If Spleeter is unavailable, the simple UI keeps the app usable by switching to full-mix mode; backend fallback also uses full-mix rather than silently launching Demucs.