# 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:

```json
{"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:

```bash
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.