Merge pull request #1509 from Adyen/error-handling-apierror

gcatanese · web-flow · commit 60dab3177546 · 2025-06-10T14:31:40.000+02:00
ApiError: Improving error handling
diff --git a/src/__tests__/balanceControl.spec.ts b/src/__tests__/balanceControl.spec.ts
@@ -65,8 +65,15 @@ describe("Balance Control", (): void => {
             fail("No exception was thrown");
         } catch (error) {
             expect(error instanceof HttpClientException).toBeTruthy();
-            if (error instanceof HttpClientException && error.responseBody && error.stack) {
-                expect(JSON.parse(error.responseBody).errorType).toBe("validation");
+            if (error instanceof HttpClientException) {
+                expect(error.statusCode).toBe(422);
+                expect(error.responseBody).toBeTruthy();
+                expect(error.errorCode).toBe("30_004");
+                // check apiError
+                expect(error.apiError).toBeTruthy();
+                expect(error.apiError?.errorCode).toBe("30_004");
+                expect(error.apiError?.message).toBe("Merchant account code is invalid or missing");
+                expect(error.apiError?.errorType).toBe("validation")
             } else {
                 fail("Error did not contain the expected data");
             }
diff --git a/src/__tests__/checkout.spec.ts b/src/__tests__/checkout.spec.ts
@@ -273,7 +273,14 @@ describe("Checkout", (): void => {
         } catch (error) {
             expect(error instanceof HttpClientException).toBeTruthy();
             if(error instanceof HttpClientException && error.responseBody && error.stack) {
-                expect(JSON.parse(error.responseBody).errorType).toBe("validation");
+                expect(error.statusCode).toBe(422);
+                expect(error.responseBody).toBeTruthy();
+                expect(error.errorCode).toBe("200");
+                // check apiError
+                expect(error.apiError).toBeTruthy();
+                expect(error.apiError?.pspReference).toBe("DMB552CV6JHKGK82");
+                expect(error.apiError?.message).toBe("Field 'countryCode' is not valid.");
+                expect(error.apiError?.errorType).toBe("validation");
             } else {
                 fail("Error did not contain the expected data");
             }
diff --git a/src/__tests__/management.spec.ts b/src/__tests__/management.spec.ts
@@ -576,9 +576,17 @@ describe("Management", (): void => {
                 await managementService.UsersMerchantLevelApi.createNewUser(merchantId, requests.createMerchantUserRequestInvalidEmail);
             } catch (error) {
                 expect(error instanceof HttpClientException).toBeTruthy();
-                if(error instanceof HttpClientException && error.responseBody && error.stack) {
-                    expect(JSON.parse(error.responseBody).status).toBe(422);
-                    expect(JSON.parse(error.responseBody).invalidFields).toBeTruthy();
+                if(error instanceof HttpClientException) {
+                    expect(error.statusCode).toBe(422);
+                    expect(error.responseBody).toBeTruthy();
+                    expect(error.errorCode).toBe("31_007");
+                    // check apiError
+                    expect(error.apiError).toBeTruthy();
+                    expect(error.apiError?.errorCode).toBe("31_007");
+                    expect(error.apiError?.title).toBe("Invalid user information provided.");
+                    expect(error.apiError?.type).toBe("https://docs.adyen.com/errors/validation")
+                    expect(error.apiError?.invalidFields).toBeTruthy();
+                    expect(error.apiError?.invalidFields?.length).toBe(1);                    
                 } else {
                     fail("Error did not contain the expected data");
                 }
diff --git a/src/__tests__/modification.spec.ts b/src/__tests__/modification.spec.ts
@@ -175,7 +175,7 @@ describe("Modification", (): void => {
     });
 
     test("should fail to perform an amount update request", async (): Promise<void> => {
-        expect.assertions(2);
+        expect.assertions(4);
         const request = createAmountUpdateRequest();
         scope.post(`/payments/${invalidPaymentPspReference}/amountUpdates`)
             .reply(422, invalidModificationResult);
@@ -184,8 +184,11 @@ describe("Modification", (): void => {
             await checkoutAPI.ModificationsApi.updateAuthorisedAmount(invalidPaymentPspReference, request);
         } catch (e) {
             if(e instanceof HttpClientException) {
-                if(e.statusCode) expect(e.statusCode).toBe(422);
+                expect(e.statusCode).toBe(422);
                 expect(e.message).toContain("Original pspReference required for this operation");
+                // check API apiError
+                expect(e.apiError).toBeTruthy();
+                expect(e.apiError?.status).toBe(422);
             } else {
                 fail();
             }
@@ -209,16 +212,20 @@ describe("Modification", (): void => {
     });
 
     test("should fail to perform a cancels request", async (): Promise<void> => {
-        expect.assertions(2);
+        expect.assertions(4);
         const request = createCancelsRequest();
         scope.post(`/payments/${invalidPaymentPspReference}/cancels`)
             .reply(422, invalidModificationResult);
         try {
             await checkoutAPI.ModificationsApi.cancelAuthorisedPaymentByPspReference(invalidPaymentPspReference, request);
         } catch (e) {
             if(e instanceof HttpClientException) {
-                if(e.statusCode) expect(e.statusCode).toBe(422);
+                expect(e.statusCode).toBe(422);
                 expect(e.message).toContain("Original pspReference required for this operation");
+                // check apiError
+                expect(e.apiError).toBeTruthy();
+                expect(e.apiError?.errorCode).toBe("167");
+
             } else {
                 fail();
             }
@@ -258,16 +265,19 @@ describe("Modification", (): void => {
     });
 
     test("should fail to perform a captures request", async (): Promise<void> => {
-        expect.assertions(2);
+        expect.assertions(4);
         const request = createCapturesRequest();
         scope.post(`/payments/${invalidPaymentPspReference}/captures`)
             .reply(422, invalidModificationResult);
         try {
             await checkoutAPI.ModificationsApi.captureAuthorisedPayment(invalidPaymentPspReference, request);
         } catch (e) {
             if(e instanceof HttpClientException) {
-                if(e.statusCode) expect(e.statusCode).toBe(422);
+                expect(e.statusCode).toBe(422);
                 expect(e.message).toContain("Original pspReference required for this operation");
+                // check apiError
+                expect(e.apiError).toBeTruthy();
+                expect(e.apiError?.errorCode).toBe("167");
             } else {
                 fail();
             }
@@ -324,16 +334,19 @@ describe("Modification", (): void => {
     });
 
     test("should fail to perform a reversals request", async (): Promise<void> => {
-        expect.assertions(2);
+        expect.assertions(4);
         const request = createReversalsRequest();
         scope.post(`/payments/${invalidPaymentPspReference}/reversals`)
             .reply(422, invalidModificationResult);
         try {
             await checkoutAPI.ModificationsApi.refundOrCancelPayment(invalidPaymentPspReference, request);
         } catch (e) {
             if(e instanceof HttpClientException) {
-                if(e.statusCode) expect(e.statusCode).toBe(422);
+                expect(e.statusCode).toBe(422);
                 expect(e.message).toContain("Original pspReference required for this operation");
+                // check apiError
+                expect(e.apiError).toBeTruthy();
+                expect(e.apiError?.errorCode).toBe("167");
             } else {
                 fail();
             }
diff --git a/src/__tests__/notification.spec.ts b/src/__tests__/notification.spec.ts
@@ -135,7 +135,7 @@ describe("Notification Test", function (): void {
 
     it("should verify the banking hmac", function (): void {
         const jsonString = "{\"data\":{\"balancePlatform\":\"Integration_tools_test\",\"accountId\":\"BA32272223222H5HVKTBK4MLB\",\"sweep\":{\"id\":\"SWPC42272223222H5HVKV6H8C64DP5\",\"schedule\":{\"type\":\"balance\"},\"status\":\"active\",\"targetAmount\":{\"currency\":\"EUR\",\"value\":0},\"triggerAmount\":{\"currency\":\"EUR\",\"value\":0},\"type\":\"pull\",\"counterparty\":{\"balanceAccountId\":\"BA3227C223222H5HVKT3H9WLC\"},\"currency\":\"EUR\"}},\"environment\":\"test\",\"type\":\"balancePlatform.balanceAccountSweep.updated\"}";
-        const isValid = hmacValidator.validateBankingHMAC("9Qz9S/0xpar1klkniKdshxpAhRKbiSAewPpWoxKefQA=", "D7DD5BA6146493707BF0BE7496F6404EC7A63616B7158EC927B9F54BB436765F", jsonString);
+        const isValid = hmacValidator.validateHMACSignature("D7DD5BA6146493707BF0BE7496F6404EC7A63616B7158EC927B9F54BB436765F", "9Qz9S/0xpar1klkniKdshxpAhRKbiSAewPpWoxKefQA=", jsonString);
         expect(isValid).toBe(true);
     });
 
diff --git a/src/helpers/getJsonResponse.ts b/src/helpers/getJsonResponse.ts
@@ -18,8 +18,6 @@
  */
 
 import Resource from "../services/resource";
-import HttpClientException from "../httpClient/httpClientException";
-import ApiException from "../services/exception/apiException";
 import { IRequest } from "../typings/requestOptions";
 
 async function getJsonResponse<T>(resource: Resource, jsonRequest: T | string, requestOptions?: IRequest.Options): Promise<string>;
@@ -29,7 +27,7 @@ async function getJsonResponse<T, R>(
     resource: Resource,
     jsonRequest: T | string,
     requestOptions: IRequest.Options = {},
-): Promise<R | string | HttpClientException | ApiException> {
+): Promise<R | string> {
     const request = typeof jsonRequest === "string" ? jsonRequest : JSON.stringify(jsonRequest);
     const response = await resource.request(request, requestOptions);
     try {
diff --git a/src/httpClient/clientInterface.ts b/src/httpClient/clientInterface.ts
@@ -17,16 +17,14 @@
  * See the LICENSE file for more info.
  */
 import { AgentOptions } from "https";
-import HttpClientException from "./httpClientException";
-import ApiException from "../services/exception/apiException";
 import { Config } from "../index";
 import { IRequest } from "../typings/requestOptions";
 
 interface ClientInterface {
     request(
         endpoint: string, json: string, config: Config, isApiKeyRequired: boolean, requestOptions?: IRequest.Options,
-    ): Promise<string | HttpClientException | ApiException>;
-    post(endpoint: string, postParameters: [string, string][], config: Config): Promise<HttpClientException | string>;
+    ): Promise<string>;
+    post(endpoint: string, postParameters: [string, string][], config: Config): Promise<string>;
     proxy?: AgentOptions;
 }
 
diff --git a/src/httpClient/httpClientException.ts b/src/httpClient/httpClientException.ts
@@ -18,13 +18,15 @@
  */
 
 import { IncomingHttpHeaders } from "http";
+import { ApiError } from "../typings/apiError";
 
 interface ExceptionInterface {
     message: string;
     statusCode?: number;
     errorCode?: string;
     responseHeaders?: IncomingHttpHeaders;
     responseBody?: string;
+    apiError?: ApiError; // model of the error returned by the API
 }
 
 class HttpClientException extends Error {
@@ -33,6 +35,7 @@ class HttpClientException extends Error {
     public responseHeaders?: IncomingHttpHeaders;
     public readonly name: string;
     public responseBody?: string;
+    public apiError?: ApiError;
 
     public constructor(props: ExceptionInterface) {
         super(props.message);
@@ -44,6 +47,7 @@ class HttpClientException extends Error {
         if (props.responseBody) this.responseBody = props.responseBody;
         if (props.errorCode) this.errorCode = props.errorCode;
         if (props.statusCode) this.statusCode = props.statusCode;
+        if (props.apiError) this.apiError = props.apiError;
     }
 }
 
diff --git a/src/httpClient/httpURLConnectionClient.ts b/src/httpClient/httpURLConnectionClient.ts
@@ -42,7 +42,7 @@ class HttpURLConnectionClient implements ClientInterface {
     public request(
         endpoint: string, json: string, config: Config, isApiRequired: boolean,
         requestOptions: IRequest.Options,
-    ): Promise<string | HttpClientException | ApiException> {
+    ): Promise<string> {
         requestOptions.headers ??= {};
         requestOptions.timeout = config.connectionTimeoutMillis;
 
@@ -71,7 +71,7 @@ class HttpURLConnectionClient implements ClientInterface {
         return this.doPostRequest(httpConnection, json);
     }
 
-    public post(endpoint: string, postParameters: [string, string][], config: Config): Promise<HttpClientException | string> {
+    public post(endpoint: string, postParameters: [string, string][], config: Config): Promise<string> {
         const postQuery: string = this.getQuery(postParameters);
         const connectionRequest: ClientRequest = this.createRequest(endpoint, {}, config.applicationName);
         return this.doPostRequest(connectionRequest, postQuery);
@@ -133,7 +133,7 @@ class HttpURLConnectionClient implements ClientInterface {
         return params.map(([key, value]): string => `${key}=${value}`).join("&");
     }
 
-    private doPostRequest(connectionRequest: ClientRequest, json: string): Promise<HttpClientException | string> {
+    private doPostRequest(connectionRequest: ClientRequest, json: string): Promise<string> {
         return new Promise((resolve, reject): void => {
             connectionRequest.flushHeaders();
 
@@ -176,6 +176,7 @@ class HttpURLConnectionClient implements ClientInterface {
                                     errorCode: formattedData.errorCode,
                                     responseHeaders: res.headers,
                                     responseBody: response.body,
+                                    apiError: formattedData,
                                 });
                             } else if (isRequestError) {
                                 exception = new Error(response.body);
diff --git a/src/services/resource.ts b/src/services/resource.ts
@@ -19,8 +19,6 @@
 
 import Config from "../config";
 import Service from "../service";
-import HttpClientException from "../httpClient/httpClientException";
-import ApiException from "./exception/apiException";
 import ClientInterface from "../httpClient/clientInterface";
 import { IRequest } from "../typings/requestOptions";
 
@@ -33,7 +31,7 @@ class Resource {
         this.endpoint = endpoint;
     }
 
-    public request(json: string, requestOptions?: IRequest.Options): Promise<string | HttpClientException | ApiException> {
+    public request(json: string, requestOptions?: IRequest.Options): Promise<string> {
         const clientInterface: ClientInterface = this.service.client.httpClient;
         const config: Config = this.service.client.config;
 
diff --git a/src/typings/apiError.ts b/src/typings/apiError.ts
@@ -17,12 +17,21 @@
  * See the LICENSE file for more info.
  */
 
-// Generated using typescript-generator version 2.14.505 on 2019-06-04 08:51:10.
-
+// ApiError interface to model Adyen API errors
+// The interface is an union of the 2 different error models used by Adyen APIs:
+// RestServiceError (based on RFC 7807)
+// ServiceError (based on the original Adyen error model).
 export interface ApiError {
     status?: number;
     errorCode?: string;
     message?: string;
     errorType?: string;
     pspReference?: string;
+
+    detail?: string
+    instance?: string;
+    invalidFields?: Array<string>;
+    requestId?: string;
+    title?: string;
+    type?: string;
 }
