Error model
Five ways a filter can be rejected
A rejected filter is answered with 400 Bad Request, and the response must say
which of these conditions applies. Which one it is decides what the client does next — so an
error that says only "bad request" is not conforming.
| Condition | Meaning |
|---|---|
malformed-query |
The body does not conform to the grammar. |
unknown-field |
The path is well-formed but this endpoint does not expose it. |
unsupported-operator |
The operator is part of the language but not of this endpoint's profiles. |
invalid-operand |
The operator is supported but the operand is not usable. |
query-too-complex |
A safety limit was exceeded. |
These URIs resolve on purpose
Where an API has no established error format, the specification recommends
RFC 9457 Problem Details
with each condition as a type URI under
https://openpredicate.tech/problems/. RFC 9457 says a type URI should dereference to
human-readable documentation, so each one above does — a developer pasting the URI from a log
lands on the explanation.
Locating the offending clause
However it is encoded, an error should carry a pointer: an
RFC 6901 JSON Pointer into
the request body. Without one, a client facing a filter with a dozen nested clauses has no way
to know which to fix. A server must also report the first error it finds rather than partially
evaluating, and should report all of them when it can.
Full normative text: specification §8.