Ошибки

Обо всех ошибках запроса клиента сообщается сразу через MyProgs\QueryBuilder\Exceptions\InvalidQueryParameters. Он наследует ValidationException Laravel, поэтому клиент получает обычный ответ 422:

GET /users?filter[age]=3&filter[posts.views][gte]=abc&sort=email

{
    "message": "Filter [age] is not allowed; allowed: name, active, created_at, posts.views, posts.status. (and 2 more errors)",
    "errors": {
        "filter.age": ["Filter [age] is not allowed; allowed: name, active, created_at, posts.views, posts.status."],
        "filter.posts.views": ["Filter [posts.views] operator [gte] expects an integer, got [abc]."],
        "sort": ["Requested sort `email` is not allowed. Allowed sorts are `name`, `created_at`, `country`, `postsCount`."]
    }
}

Коды ошибок

$exception->details содержит те же ошибки как объекты QueryError с параметром, кодом и разрешёнными значениями. Если клиенту нужны машиночитаемые коды, отдавайте их в своём обработчике исключений:

{ "parameter": "filter.age", "code": "unknown_filter", "message": "...", "allowed": ["name", "active", "created_at", "posts.views", "posts.status"] }

Коды — это значения QueryErrorCode:

Код	Значение
unknown_filter	фильтр не разрешён
unknown_sort	сортировка не разрешена
unknown_include	include не разрешён
unknown_field	поле не разрешено
unknown_append	append не поддерживается
unknown_operator	такого оператора нет
operator_not_allowed	фильтр не разрешает этот оператор
invalid_value	значение не подходит под тип фильтра
invalid_arity	неверное число значений (between нужно два)
ambiguous_fields	к одному пути обращаются два ключа fields
invalid_page	page или per_page вне допустимого диапазона
nulls_not_allowed	суффикс :nulls-* на сортировке без clientNulls()

unknown_include перечисляет подгрузки связей, разрешённые там, где запрос клиента ошибся: первый уровень для include=foo, подгрузки под posts для include=posts.foo.

Битый параметр (массив там, где ожидается строка) — это 400 MalformedQueryParameter, как и в spatie-совместимом API.

Переводы

Сообщения следуют локали приложения (App::setLocale(), ключи locale и fallback_locale в config/app.php). Пакет поставляется с английским и русским, а локаль без перевода получает резервный (английский, если перевода нет и для резервной). Коды, параметры и разрешённые значения одинаковы на всех языках.

Суффикс (and 2 more errors) в message добавляет сам Laravel; он переводится через lang/<locale>.json приложения.

Чтобы изменить формулировки или добавить язык, опубликуйте переводы в lang/vendor/query-builder и правьте их там:

php artisan vendor:publish --tag=query-builder-translations

Переводится только definitions API: сообщения исключений spatie-совместимого API (InvalidFilterQuery и другие) остаются на английском, как в spatie.

Ошибки в определении

Ошибка в самом определении (неизвестный оператор для типа, сортировка по связи без колонки, путь через morphTo без типов) бросает InvalidArgumentException. Это баг в вашем коде, а не в запросе клиента.