YARA-1135

src/request-management/file-maker-claim-approval-v5.controller.ts

@@ -10,6 +10,7 @@ import {
   ApiBody,
   ApiOperation,
   ApiParam,
+  ApiResponse,
   ApiTags,
 } from "@nestjs/swagger";
 import { IsOptional, IsString } from "class-validator";
@@ -91,9 +92,28 @@ export class FileMakerClaimApprovalV5Controller {
   @ApiOperation({
     summary: "Reject the completed claim back to FileReviewer (FileMaker V5)",
     description:
-      "Rejects a claim that is in WAITING_FOR_FILE_MAKER_APPROVAL status. " +
-      "Moves claim to FILE_MAKER_REJECTED so the FileReviewer can re-lock, " +
-      "adjust the damage assessment, and restart user interaction as needed.",
+      "Rejects a claim that is in `WAITING_FOR_FILE_MAKER_APPROVAL` status. " +
+      "Moves the claim back to `WAITING_FOR_DAMAGE_EXPERT` and the linked blame back to " +
+      "`WAITING_FOR_FILE_REVIEWER` so the FileReviewer can re-lock, adjust the damage " +
+      "assessment, and restart user interaction as needed.\n\n" +
+      "**Rejection limit:** the FileMaker may reject at most **2 times** per claim. " +
+      "On the 3rd attempt the endpoint returns **422** with " +
+      "`errorCode: FILE_MAKER_REJECTION_LIMIT_EXCEEDED` — the FileMaker must approve instead. " +
+      "The current count is returned as `fileMakerRejectionCount` in the response and in " +
+      "`GET v2/expert-claim/requests`.",
+  })
+  @ApiResponse({
+    status: 422,
+    description:
+      "Business rule violation: rejection limit exceeded. " +
+      "`errorCode: FILE_MAKER_REJECTION_LIMIT_EXCEEDED` — the claim has already been rejected twice.",
+    schema: {
+      example: {
+        errorCode: "FILE_MAKER_REJECTION_LIMIT_EXCEEDED",
+        message:
+          "This claim has already been rejected twice. You must approve it now — no further rejections are allowed.",
+      },
+    },
   })
   async reject(
     @Param("claimRequestId") claimRequestId: string,