feat: return 422 for malformed OpenSearch query syntax (#15)

Detect OpenSearch 400 errors (e.g. parsing_exception from invalid
query_string syntax) and return a 422 with INVALID_REQUEST error code
instead of a generic 500.

Author: johnf

src/routes/search.test.ts

@@ -2,6 +2,7 @@ import { afterEach, beforeEach, describe, expect, it } from 'vitest';
 
 import { fastify, fastifyAfter, fastifyBefore, opensearch, prisma } from '../test/helpers/fastify.js';
 import { AllPublicAccessTransformer } from '../transformers/default.js';
+import type { StandardErrorResponse } from '../utils/errors.js';
 import searchRoute from './search.js';
 
 describe('Search Route', () => {
@@ -379,6 +380,24 @@ describe('Search Route', () => {
       );
     });
 
+    it('should return 422 for malformed opensearch query', async () => {
+      const opensearchError = Object.assign(new Error('parsing_exception'), { statusCode: 400 });
+      opensearch.search.mockRejectedValue(opensearchError);
+
+      const response = await fastify.inject({
+        method: 'POST',
+        url: '/search',
+        payload: {
+          query: 'test',
+          searchType: 'advanced',
+        },
+      });
+
+      expect(response.statusCode).toBe(422);
+      const body = JSON.parse(response.body) as StandardErrorResponse;
+      expect(body.error.code).toBe('INVALID_REQUEST');
+    });
+
     it('should handle opensearch errors', async () => {
       opensearch.search.mockRejectedValue(new Error('OpenSearch connection failed'));
 

src/routes/search.ts

@@ -5,7 +5,7 @@ import type { ZodTypeProvider } from 'fastify-type-provider-zod';
 import { z } from 'zod/v4';
 import { baseEntityTransformer, resolveEntityReferences } from '../transformers/default.js';
 import type { AccessTransformer, EntityTransformer } from '../types/transformers.js';
-import { createInternalError } from '../utils/errors.js';
+import { createInternalError, createInvalidRequestError } from '../utils/errors.js';
 import { OpensearchQueryBuilder, type QueryBuilderOptions } from '../utils/queryBuilder.js';
 
 const boundingBoxSchema = z.object({
@@ -183,6 +183,14 @@ const search: FastifyPluginAsync<SearchRouteOptions> = async (fastify, opts) =>
         return result;
       } catch (error) {
         const err = error as Error;
+
+        // OpenSearch returns 400 for malformed queries (e.g. invalid query_string syntax)
+        if ('statusCode' in err && (err as { statusCode: number }).statusCode === 400) {
+          fastify.log.warn(`Invalid search query: ${err.message}`);
+
+          return reply.code(422).send(createInvalidRequestError(err.message));
+        }
+
         fastify.log.error(`Search error: ${err.message}`);
 
         return reply.code(500).send(createInternalError('Search failed'));

src/utils/errors.ts

@@ -41,6 +41,9 @@ export const createValidationError = (message: string, violations: ValidationVio
 export const createNotFoundError = (message: string, entityId?: string): StandardErrorResponse =>
   createErrorResponse(ERROR_CODES.NOT_FOUND, message, entityId ? { entityId } : undefined);
 
+export const createInvalidRequestError = (message: string): StandardErrorResponse =>
+  createErrorResponse(ERROR_CODES.INVALID_REQUEST, message);
+
 export const createInternalError = (message = 'Internal server error'): StandardErrorResponse => {
   return createErrorResponse(ERROR_CODES.INTERNAL_ERROR, message);
 };