CCM-12590 - Update failure reason code to string (#234)

nhsd-david-wass · web-flow · commit 38c1fa6676e6 · 2025-11-17T09:40:41.000Z
* CCM-12590 - Update failure reason code to string * Update sandbox and OAS descriptions
diff --git a/docs/assets/diagrams/types.md b/docs/assets/diagrams/types.md
@@ -13,7 +13,7 @@ erDiagram
         string status "enum: PENDING, ACCEPTED, REJECTED, PRINTED, ENCLOSED, CANCELLED, DISPATCHED, FAILED, RETURNED, FORWARDED, DELIVERED"
         string specificationId
         string groupId
-        number reasonCode
+        string reasonCode
         string reasonText
         string supplierId
         string url "url"
diff --git a/internal/datastore/src/__test__/letter-repository.test.ts b/internal/datastore/src/__test__/letter-repository.test.ts
@@ -111,14 +111,14 @@ describe('LetterRepository', () => {
       id: 'letter1',
       supplierId: 'supplier1',
       status: 'REJECTED',
-      reasonCode: 1,
+      reasonCode: 'R01',
       reasonText: 'Reason text'
     };
     await letterRepository.updateLetterStatus(letterDto);
 
     const updatedLetter = await letterRepository.getLetterById('supplier1', 'letter1');
     expect(updatedLetter.status).toBe('REJECTED');
-    expect(updatedLetter.reasonCode).toBe(1);
+    expect(updatedLetter.reasonCode).toBe('R01');
     expect(updatedLetter.reasonText).toBe('Reason text');
   });
 
diff --git a/internal/datastore/src/types.md b/internal/datastore/src/types.md
@@ -13,7 +13,7 @@ erDiagram
         string status "enum: PENDING, ACCEPTED, REJECTED, PRINTED, ENCLOSED, CANCELLED, DISPATCHED, FAILED, RETURNED, FORWARDED, DELIVERED"
         string specificationId
         string groupId
-        number reasonCode
+        string reasonCode
         string reasonText
         string supplierId
         string url "url"
diff --git a/internal/datastore/src/types.ts b/internal/datastore/src/types.ts
@@ -24,7 +24,7 @@ export const LetterSchemaBase = z.object({
   status: LetterStatus,
   specificationId: z.string(),
   groupId: z.string(),
-  reasonCode: z.number().optional(),
+  reasonCode: z.string().optional(),
   reasonText: z.string().optional()
 });
 
diff --git a/lambdas/api-handler/src/contracts/letters.ts b/lambdas/api-handler/src/contracts/letters.ts
@@ -7,7 +7,7 @@ export type LetterDto = {
   supplierId: string,
   specificationId?: string,
   groupId?: string,
-  reasonCode?: number,
+  reasonCode?: string,
   reasonText?: string
 };
 
@@ -30,7 +30,7 @@ export const PatchLetterRequestResourceSchema = z.object({
   type: z.literal('Letter'),
   attributes: z.object({
     status: LetterStatusSchema,
-    reasonCode: z.number().optional(),
+    reasonCode: z.string().optional(),
     reasonText: z.string().optional(),
   }).strict()
 }).strict();
@@ -42,7 +42,7 @@ export const GetLetterResponseResourceSchema = z.object({
     status: LetterStatusSchema,
     specificationId: z.string(),
     groupId: z.string().optional(),
-    reasonCode: z.number().optional(),
+    reasonCode: z.string().optional(),
     reasonText: z.string().optional(),
   }).strict()
 }).strict();
diff --git a/lambdas/api-handler/src/handlers/__tests__/get-letter.test.ts b/lambdas/api-handler/src/handlers/__tests__/get-letter.test.ts
@@ -78,7 +78,7 @@ describe('API Lambda handler', () => {
       specificationId: 'spec1',
       groupId: 'group1',
       status: 'FAILED',
-      reasonCode: 100,
+      reasonCode: 'R01',
       reasonText: 'failed validation'
     });
 
@@ -97,7 +97,7 @@ describe('API Lambda handler', () => {
           status: 'FAILED',
           specificationId: 'spec1',
           groupId: 'group1',
-          reasonCode: 100,
+          reasonCode: 'R01',
           reasonText: 'failed validation'
         }
       }
diff --git a/lambdas/api-handler/src/handlers/__tests__/get-letters.test.ts b/lambdas/api-handler/src/handlers/__tests__/get-letters.test.ts
@@ -65,7 +65,7 @@ describe('API Lambda handler', () => {
         specificationId: 's1',
         groupId: 'g1',
         status: 'PENDING',
-        reasonCode: 123, // shouldn't be returned if present
+        reasonCode: 'R02', // shouldn't be returned if present
         reasonText: 'Reason text' // shouldn't be returned if present
       },
     ]);
diff --git a/lambdas/api-handler/src/handlers/__tests__/patch-letter.test.ts b/lambdas/api-handler/src/handlers/__tests__/patch-letter.test.ts
@@ -32,7 +32,7 @@ const updateLetterStatusRequest : PatchLetterRequest = {
       type: 'Letter',
       attributes: {
         status: 'REJECTED',
-        reasonCode: 123,
+        reasonCode: 'R01',
         reasonText: 'Reason text',
       }
     }
@@ -81,7 +81,7 @@ describe('patchLetter API Handler', () => {
             status: 'REJECTED',
             specificationId: 'spec1',
             groupId: 'group1',
-            reasonCode: 123,
+            reasonCode: 'R01',
             reasonText: 'Reason text',
           }
         }
diff --git a/lambdas/api-handler/src/mappers/__tests__/letter-mapper.test.ts b/lambdas/api-handler/src/mappers/__tests__/letter-mapper.test.ts
@@ -46,7 +46,7 @@ describe('letter-mapper', () => {
       supplierStatus: 'supplier1#PENDING',
       supplierStatusSk: Date.now().toString(),
       ttl: 123,
-      reasonCode: 123,
+      reasonCode: 'R01',
       reasonText: 'Reason text'
     };
 
@@ -60,7 +60,7 @@ describe('letter-mapper', () => {
           specificationId: 'spec123',
           status: 'PENDING',
           groupId: 'group123',
-          reasonCode: 123,
+          reasonCode: 'R01',
           reasonText: 'Reason text',
         }
       }
@@ -111,7 +111,7 @@ describe('letter-mapper', () => {
       supplierStatus: 'supplier1#PENDING',
       supplierStatusSk: Date.now().toString(),
       ttl: 123,
-      reasonCode: 123,
+      reasonCode: 'R01',
       reasonText: 'Reason text'
     };
 
@@ -125,7 +125,7 @@ describe('letter-mapper', () => {
           specificationId: 'spec123',
           status: 'PENDING',
           groupId: 'group123',
-          reasonCode: 123,
+          reasonCode: 'R01',
           reasonText: 'Reason text',
         }
       }
@@ -145,7 +145,7 @@ describe('letter-mapper', () => {
       supplierStatus: 'supplier1#PENDING',
       supplierStatusSk: Date.now().toString(),
       ttl: 123,
-      reasonCode: 123,
+      reasonCode: 'R01',
       reasonText: 'Reason text'
     };
 
diff --git a/lambdas/api-handler/src/services/__tests__/letter-operations.test.ts b/lambdas/api-handler/src/services/__tests__/letter-operations.test.ts
@@ -102,7 +102,7 @@ describe('patchLetterStatus function', () => {
     id: 'letter1',
     supplierId: 'supplier1',
     status: 'REJECTED',
-    reasonCode: 123,
+    reasonCode: 'R01',
     reasonText: 'Reason text'
   };
 
@@ -223,7 +223,7 @@ function makeLetter(id: string, status: Letter['status']) : Letter {
       supplierStatus: `supplier1#${status}`,
       supplierStatusSk: Date.now().toString(),
       ttl: 123,
-      reasonCode: 123,
+      reasonCode: 'R01',
       reasonText: "Reason text"
   };
 }
diff --git a/postman/Sandbox.postman_collection.json b/postman/Sandbox.postman_collection.json
@@ -754,7 +754,7 @@
                           "language": "json"
                         }
                       },
-                      "raw": "\n{\n  \"data\": {\n    \"attributes\": {\n      \"reasonCode\": 100,\n      \"reasonText\": \"failed validation\",\n      \"status\": \"CANCELLED\"\n    },\n    \"id\": \"2WL5eYSWGzCHlGmzNxuqVusPxDg\",\n    \"type\": \"Letter\"\n  }\n}"
+                      "raw": "\n{\n  \"data\": {\n    \"attributes\": {\n      \"reasonCode\": 'R01',\n      \"reasonText\": \"failed validation\",\n      \"status\": \"CANCELLED\"\n    },\n    \"id\": \"2WL5eYSWGzCHlGmzNxuqVusPxDg\",\n    \"type\": \"Letter\"\n  }\n}"
                     },
                     "header": [
                       {
@@ -1014,7 +1014,7 @@
                           "language": "json"
                         }
                       },
-                      "raw": "{\n  \"data\": {\n    \"attributes\": {\n      \"reasonCode\": 100,\n      \"reasonText\": \"failed validation\",\n      \"status\": \"FAILED\"\n    },\n    \"id\": \"2WL5eYSWGzCHlGmzNxuqVusPxDg\",\n    \"type\": \"Letter\"\n  }\n}"
+                      "raw": "{\n  \"data\": {\n    \"attributes\": {\n      \"reasonCode\": 'R01',\n      \"reasonText\": \"failed validation\",\n      \"status\": \"FAILED\"\n    },\n    \"id\": \"2WL5eYSWGzCHlGmzNxuqVusPxDg\",\n    \"type\": \"Letter\"\n  }\n}"
                     },
                     "header": [
                       {
@@ -1451,7 +1451,7 @@
                       "language": "json"
                     }
                   },
-                  "raw": "{\n  \"data\": [\n    {\n      \"attributes\": {\n        \"status\": \"PENDING\"\n      },\n      \"id\": \"2WL5eYSWGzCHlGmzNxuqVusPxDg\",\n      \"type\": \"Letter\"\n    },\n    {\n      \"attributes\": {\n        \"status\": \"ACCEPTED\"\n      },\n      \"id\": \"2WL5eYSWGzCHlGmzNxuqVusPxDg\",\n      \"type\": \"Letter\"\n    },\n    {\n      \"attributes\": {\n        \"status\": \"PRINTED\"\n      },\n      \"id\": \"2WL5eYSWGzCHlGmzNxuqVusPxDg\",\n      \"type\": \"Letter\"\n    },\n    {\n      \"attributes\": {\n        \"status\": \"ENCLOSED\"\n      },\n      \"id\": \"2WL5eYSWGzCHlGmzNxuqVusPxDg\",\n      \"type\": \"Letter\"\n    },\n    {\n      \"attributes\": {\n        \"status\": \"DISPATCHED\"\n      },\n      \"id\": \"2WL5eYSWGzCHlGmzNxuqVusPxDg\",\n      \"type\": \"Letter\"\n    },\n    {\n      \"attributes\": {\n        \"status\": \"DELIVERED\"\n      },\n      \"id\": \"2WL5eYSWGzCHlGmzNxuqVusPxDg\",\n      \"type\": \"Letter\"\n    },\n    {\n      \"attributes\": {\n        \"reasonCode\": 100,\n        \"reasonText\": \"failed validation\",\n        \"status\": \"RETURNED\"\n      },\n      \"id\": \"2WL5eYSWGzCHlGmzNxuqVusPxDg\",\n      \"type\": \"Letter\"\n    },\n    {\n      \"attributes\": {\n        \"reasonCode\": 100,\n        \"reasonText\": \"failed validation\",\n        \"status\": \"CANCELLED\"\n      },\n      \"id\": \"2WL5eYSWGzCHlGmzNxuqVusPxDg\",\n      \"type\": \"Letter\"\n    },\n    {\n      \"attributes\": {\n        \"reasonCode\": 100,\n        \"reasonText\": \"failed validation\",\n        \"status\": \"FAILED\"\n      },\n      \"id\": \"2WL5eYSWGzCHlGmzNxuqVusPxDg\",\n      \"type\": \"Letter\"\n    },\n    {\n      \"attributes\": {\n        \"reasonCode\": 100,\n        \"reasonText\": \"failed validation\",\n        \"status\": \"RETURNED\"\n      },\n      \"id\": \"2WL5eYSWGzCHlGmzNxuqVusPxDg\",\n      \"type\": \"Letter\"\n    }\n  ]\n}"
+                  "raw": "{\n  \"data\": [\n    {\n      \"attributes\": {\n        \"status\": \"PENDING\"\n      },\n      \"id\": \"2WL5eYSWGzCHlGmzNxuqVusPxDg\",\n      \"type\": \"Letter\"\n    },\n    {\n      \"attributes\": {\n        \"status\": \"ACCEPTED\"\n      },\n      \"id\": \"2WL5eYSWGzCHlGmzNxuqVusPxDg\",\n      \"type\": \"Letter\"\n    },\n    {\n      \"attributes\": {\n        \"status\": \"PRINTED\"\n      },\n      \"id\": \"2WL5eYSWGzCHlGmzNxuqVusPxDg\",\n      \"type\": \"Letter\"\n    },\n    {\n      \"attributes\": {\n        \"status\": \"ENCLOSED\"\n      },\n      \"id\": \"2WL5eYSWGzCHlGmzNxuqVusPxDg\",\n      \"type\": \"Letter\"\n    },\n    {\n      \"attributes\": {\n        \"status\": \"DISPATCHED\"\n      },\n      \"id\": \"2WL5eYSWGzCHlGmzNxuqVusPxDg\",\n      \"type\": \"Letter\"\n    },\n    {\n      \"attributes\": {\n        \"status\": \"DELIVERED\"\n      },\n      \"id\": \"2WL5eYSWGzCHlGmzNxuqVusPxDg\",\n      \"type\": \"Letter\"\n    },\n    {\n      \"attributes\": {\n        \"reasonCode\": 'R01',\n        \"reasonText\": \"failed validation\",\n        \"status\": \"RETURNED\"\n      },\n      \"id\": \"2WL5eYSWGzCHlGmzNxuqVusPxDg\",\n      \"type\": \"Letter\"\n    },\n    {\n      \"attributes\": {\n        \"reasonCode\": 'R01',\n        \"reasonText\": \"failed validation\",\n        \"status\": \"CANCELLED\"\n      },\n      \"id\": \"2WL5eYSWGzCHlGmzNxuqVusPxDg\",\n      \"type\": \"Letter\"\n    },\n    {\n      \"attributes\": {\n        \"reasonCode\": 'R01',\n        \"reasonText\": \"failed validation\",\n        \"status\": \"FAILED\"\n      },\n      \"id\": \"2WL5eYSWGzCHlGmzNxuqVusPxDg\",\n      \"type\": \"Letter\"\n    },\n    {\n      \"attributes\": {\n        \"reasonCode\": 'R01',\n        \"reasonText\": \"failed validation\",\n        \"status\": \"RETURNED\"\n      },\n      \"id\": \"2WL5eYSWGzCHlGmzNxuqVusPxDg\",\n      \"type\": \"Letter\"\n    }\n  ]\n}"
                 },
                 "header": [
                   {
diff --git a/sandbox/data/examples/patchLetter/requests/patchLetter_CANCELLED.json b/sandbox/data/examples/patchLetter/requests/patchLetter_CANCELLED.json
@@ -1,8 +1,8 @@
 {
   "data": {
     "attributes": {
-      "reasonCode": "R01",
-      "reasonText": "failed validation",
+      "reasonCode": "R10",
+      "reasonText": "Miscellaneous",
       "status": "CANCELLED"
     },
     "id": "2WL5eYSWGzCHlGmzNxuqVusPxDg",
diff --git a/sandbox/data/examples/patchLetter/requests/patchLetter_FAILED.json b/sandbox/data/examples/patchLetter/requests/patchLetter_FAILED.json
@@ -1,8 +1,8 @@
 {
   "data": {
     "attributes": {
-      "reasonCode": "R01",
-      "reasonText": "failed validation",
+      "reasonCode": "R10",
+      "reasonText": "Miscellaneous",
       "status": "FAILED"
     },
     "id": "2WL5eYSWGzCHlGmzNxuqVusPxDg",
diff --git a/sandbox/data/examples/patchLetter/requests/patchLetter_REJECTED.json b/sandbox/data/examples/patchLetter/requests/patchLetter_REJECTED.json
@@ -1,8 +1,8 @@
 {
   "data": {
     "attributes": {
-      "reasonCode": "R01",
-      "reasonText": "failed validation",
+      "reasonCode": "R07",
+      "reasonText": "No such address",
       "status": "REJECTED"
     },
     "id": "2WL5eYSWGzCHlGmzNxuqVusPxDg",
diff --git a/sandbox/data/examples/patchLetter/requests/patchLetter_RETURNED.json b/sandbox/data/examples/patchLetter/requests/patchLetter_RETURNED.json
@@ -2,7 +2,7 @@
   "data": {
     "attributes": {
       "reasonCode": "R01",
-      "reasonText": "failed validation",
+      "reasonText": "Addressee gone away",
       "status": "REJECTED"
     },
     "id": "2WL5eYSWGzCHlGmzNxuqVusPxDg",
diff --git a/sandbox/data/examples/patchLetter/responses/patchLetter_CANCELLED.json b/sandbox/data/examples/patchLetter/responses/patchLetter_CANCELLED.json
@@ -1,8 +1,8 @@
 {
   "data": {
     "attributes": {
-      "reasonCode": "R01",
-      "reasonText": "failed validation",
+      "reasonCode": "R10",
+      "reasonText": "Miscellaneous",
       "specificationId": "2WL5eYSWGzCHlGmzNxuqVusPxDg",
       "status": "CANCELLED"
     },
diff --git a/sandbox/data/examples/patchLetter/responses/patchLetter_FAILED.json b/sandbox/data/examples/patchLetter/responses/patchLetter_FAILED.json
@@ -1,8 +1,8 @@
 {
   "data": {
     "attributes": {
-      "reasonCode": "R01",
-      "reasonText": "failed validation",
+      "reasonCode": "R10",
+      "reasonText": "Miscellaneous",
       "specificationId": "2WL5eYSWGzCHlGmzNxuqVusPxDg",
       "status": "FAILED"
     },
diff --git a/sandbox/data/examples/patchLetter/responses/patchLetter_REJECTED.json b/sandbox/data/examples/patchLetter/responses/patchLetter_REJECTED.json
@@ -1,8 +1,8 @@
 {
   "data": {
     "attributes": {
-      "reasonCode": "R01",
-      "reasonText": "failed validation",
+      "reasonCode": "R07",
+      "reasonText": "No such address",
       "specificationId": "2WL5eYSWGzCHlGmzNxuqVusPxDg",
       "status": "REJECTED"
     },
diff --git a/sandbox/data/examples/patchLetter/responses/patchLetter_RETURNED.json b/sandbox/data/examples/patchLetter/responses/patchLetter_RETURNED.json
@@ -2,7 +2,7 @@
   "data": {
     "attributes": {
       "reasonCode": "R01",
-      "reasonText": "failed validation",
+      "reasonText": "Addressee gone away",
       "specificationId": "2WL5eYSWGzCHlGmzNxuqVusPxDg",
       "status": "RETURNED"
     },
diff --git a/specification/api/components/documentation/getLetterStatus.md b/specification/api/components/documentation/getLetterStatus.md
@@ -20,3 +20,20 @@ You can test the following scenarios in our sandbox environment
 | Retrieve a CANCELLED letter status      | `2XL5eYSWGzCHlGmzNxuqVusPxDg`|
 | Retrieve a FAILED letter status         | `2YL5eYSWGzCHlGmzNxuqVusPxDg`|
 | Retrieve a RETURNED letter status       | `2ZL5eYSWGzCHlGmzNxuqVusPxDg`|
+
+### Example Error Codes
+
+Examples of reason codes and text that may be returned include (but are not limited to)
+
+| Reason Code | Reason Text                |
+|-------------|----------------------------|
+|R01          |Addressee gone away         |
+|R02          |Address incomplete          |
+|R03          |Address inaccessible        |
+|R04          |Addressee unknown           |
+|R05          |Addressee gone away/Refused |
+|R06          |Not called for              |
+|R07          |No such address             |
+|R08          |No reason given             |
+|R09          |Deceased                    |
+|R10          |Miscellaneous               |
diff --git a/specification/api/components/documentation/patchLetter.md b/specification/api/components/documentation/patchLetter.md
@@ -24,3 +24,20 @@ Allowed `status` values that can be used to are:
 It is not possible to update a letter to status of `PENDING`.
 
 Optionally a `reasonCode` and `reasonText` explaining the status (for example, validation failures) can be included in the request body.
+
+### Example Error Codes
+
+Examples of reason codes and text that may be returned include (but are not limited to)
+
+| Reason Code | Reason Text                |
+|-------------|----------------------------|
+|R01          |Addressee gone away         |
+|R02          |Address incomplete          |
+|R03          |Address inaccessible        |
+|R04          |Addressee unknown           |
+|R05          |Addressee gone away/Refused |
+|R06          |Not called for              |
+|R07          |No such address             |
+|R08          |No reason given             |
+|R09          |Deceased                    |
+|R10          |Miscellaneous               |
diff --git a/specification/api/components/documentation/postLetters.md b/specification/api/components/documentation/postLetters.md
@@ -26,3 +26,20 @@ Allowed `status` values that can be used to are:
 It is not possible to update a letter to status of `PENDING`.
 
 Optionally a `reasonCode` and `reasonText` explaining the status (for example, validation failures) can be included in the request body for each update.
+
+### Example Error Codes
+
+Examples of reason codes and text that may be returned include (but are not limited to)
+
+| Reason Code | Reason Text                |
+|-------------|----------------------------|
+|R01          |Addressee gone away         |
+|R02          |Address incomplete          |
+|R03          |Address inaccessible        |
+|R04          |Addressee unknown           |
+|R05          |Addressee gone away/Refused |
+|R06          |Not called for              |
+|R07          |No such address             |
+|R08          |No reason given             |
+|R09          |Deceased                    |
+|R10          |Miscellaneous               |
diff --git a/tests/component-tests/apiGateway-tests/testCases/UpdateLetterStatus.ts b/tests/component-tests/apiGateway-tests/testCases/UpdateLetterStatus.ts
@@ -8,7 +8,7 @@ export type PatchMessageRequestBody = {
     type: string;
     id: string;
     attributes: {
-      reasonCode?: string | number;
+      reasonCode?: string;
       reasonText?: string;
       status: string;
     };
@@ -20,7 +20,7 @@ export type PatchMessageResponseBody = {
     type: string;
     id: string;
     attributes: {
-      reasonCode?: number;
+      reasonCode?: string;
       reasonText?: string;
       status: string;
       specificationId:string;
@@ -64,7 +64,7 @@ export function patchFailureRequestBody (id: string, status: string) : PatchMess
     data: {
         attributes: {
           status: status,
-          reasonCode: 123,
+          reasonCode: 'R01',
           reasonText: 'Test Reason'
       },
       type: 'Letter',
diff --git a/tests/sandbox/testCases/getLetterStatus_testCases.ts b/tests/sandbox/testCases/getLetterStatus_testCases.ts
diff --git a/tests/sandbox/testCases/updateLetterStatus_testCases.ts b/tests/sandbox/testCases/updateLetterStatus_testCases.ts
diff --git a/tests/sandbox/testCases/updateMultipleStatus_testCases.ts b/tests/sandbox/testCases/updateMultipleStatus_testCases.ts

Original file line number	Diff line number	Diff line change
`@@ -32,7 +32,7 @@ const updateLetterStatusRequest : PatchLetterRequest = {`
`32`	`32`	`type: 'Letter',`
`33`	`33`	`attributes: {`
`34`	`34`	`status: 'REJECTED',`
`35`		`- reasonCode: 123,`
	`35`	`+ reasonCode: 'R01',`
`36`	`36`	`reasonText: 'Reason text',`
`37`	`37`	`}`
`38`	`38`	`}`
`@@ -81,7 +81,7 @@ describe('patchLetter API Handler', () => {`
`81`	`81`	`status: 'REJECTED',`
`82`	`82`	`specificationId: 'spec1',`
`83`	`83`	`groupId: 'group1',`
`84`		`- reasonCode: 123,`
	`84`	`+ reasonCode: 'R01',`
`85`	`85`	`reasonText: 'Reason text',`
`86`	`86`	`}`
`87`	`87`	`}`