Skip to content

STAC API: invalid query and filter values return 500 instead of 400 #383

Open

Description

@cgiovando

Invalid query and filter values on the STAC API return HTTP 500 instead of 400.

Request Status Response
/stac/collections?query=maxar 500 JSONDecodeError: unexpected character: line 1 column 1 (char 0)
/stac/search?query=maxar 500 JSONDecodeError (same)
/stac/collections?query="maxar" 500 InvalidParameterValueError: cannot call jsonb_each on a non-object
/stac/collections?filter=bad( 500 CQL2 parse error
/stac/search?filter=bad( 500 CQL2 parse error
/stac/collections?query={"id":{"eq":"openaerialmap"}} 200 1 collection
/stac/collections?q=maxar 200 1 collection

(Query strings shown unencoded for readability.)

Parse and validation errors in query and filter should be mapped to a 400 with a clear message, on both /search and /collections, with tests for malformed JSON, non-object JSON and invalid CQL2. Catching only JSON decode errors would leave the other cases returning 500.

Separately, backend/stac-api/app/main.py enables the Query extension for collection search and advertises collection-search#query. The Collection Search spec says Query is not available for collection search and points to Filter instead, so it could be dropped there (item search keeps it).

A smaller point on q: the API advertises basic free-text (collection-search#free-text), but q behaves like neither basic nor advanced free-text. OR and AND work as operators, while unqualified words are matched as a phrase in order:

q= Collections
OpenAerialMap 3
OpenAerialMap OR zzqxnonsense 3
OpenAerialMap AND satellite 1
OpenAerialMap satellite 0
Open Data Catalog 2
Catalog Open 0
OpenAerialMap,zzqxnonsense 3

Commas behave as basic free-text expects. Advertising advanced would not fix the mismatch, since advanced treats unqualified words as OR. Aligning q with one of the two, or documenting the current behaviour, would let clients rely on it.

Activity

  1. linear commented on Nov 6, 2026

    @linear
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Metadata

Metadata

Assignees

No one assigned

    Type

    No type

    Projects

    No projects

      Milestone

      No milestone

      Relationships

      None yet

      Development

      No branches or pull requests

      Issue actions