Year, make and model is how customers describe cars and how most forms collect them. It is also not always enough to identify one. The same model year can ship with two drivetrains, two engines or two trim levels that take different parts, and picking one silently is the kind of error nobody notices until a part does not fit.
So an ambiguous lookup answers 409 with the candidates attached.
GET /v1/fluids?year=2019&make=Honda&model=CR-V{ "error": "multiple_matches", "matches": [ { "config_key": "2019_honda_cr_v_ex_l15be" }, { "config_key": "2019_honda_cr_v_ex_l15be_2wd" } ] }Three ways to resolve it
- Add a trim to the query and try again, when your form has one.
- Show the candidates to the person in front of you. They usually know which car is theirs.
- Ask first: GET /v1/configs returns the same list as a 200, with the enrichment status and fill rate for each, so you can present them without triggering an error path.
Why this is not a failure
A 409 is the API telling you it has more than one right answer, which is more useful than a 200 carrying one of them. The status code exists so an integration can branch on it deliberately rather than parse a message. Everything the response needs to recover is in the body: pick a config_key, repeat the call, and store the key so the question never comes up again for that vehicle.
The one thing not to do is retry the same query and hope. The list is deterministic; the ambiguity is real.