如何查看Query API返回的Bad Request错误详细信息

Vespa 默认不会在400响应中返回完整错误细节，避免内部结构信息泄露，可通过以下方式定位具体问题：

• 开启请求级别的错误追踪：发起POST请求时追加查询参数trace.level=1，或添加请求头X-Vespa-Trace-Level: 1，响应体中会新增trace节点，其中errors数组会明确标注错误原因，常见如YQL语法错误、参数格式非法、必填字段缺失、参数值超出合法范围等问题都会直接展示。如果需要查看完整的请求解析链路，可将trace级别调高到3，定位400问题用级别1足够。
• 正确检索服务端日志：使用vespa-logfmt未找到相关记录，通常是日志级别过滤不全导致的——400类请求校验错误大多属于warning级别，而非error级别。在搜索容器节点执行命令vespa-logfmt -s searchcontainer -l warning,error即可看到所有请求解析阶段的异常记录；如果是多节点集群，需要在所有容器节点执行检索，避免请求负载均衡到其他节点漏查日志。也可以加-f参数开启实时日志跟踪，复现请求时就能看到同步打印的错误详情，会标注具体出错的参数位置和原因。
• 排查基础请求配置问题：使用OkHttpClient发起POST请求时，优先检查Content-Type请求头是否正确设置为application/json，如果头配置错误，Vespa会将JSON请求体按表单格式解析，直接返回400且无额外提示。同时核对请求体结构，确认yql、hits、offset等参数的层级、格式符合接口要求，没有出现字段拼写错误、类型不匹配的问题。

可先用curl快速复现验证，执行时加上trace参数即可直接拿到错误详情，示例命令：

curl -v -X POST -H "Content-Type: application/json" --data @本地请求体文件路径 http://<Vespa服务地址>:8080/search/?trace.level=1

内容的提问来源于stack exchange，提问作者masterllama