docs: document HTTP error mapping for ICM errors (#339)

docs/README.md

@@ -33,6 +33,7 @@ kb_sync_latest_only
   - [Guide - Testing with Jest](./guides/testing-jest.md)
   - [Guide - Testing with Cypress](./guides/testing-cypress.md)
   - [Guide - State Management > Testing](./guides/state-management.md#testing-ngrx-artifacts)
+- [Guide - ICM HTTP Error Mapping](./guides/icm-http-error-mapping.md)
 - [Guide - Code Documentation](./guides/code-documentation.md)
 - [Guide - Angular Change Detection](./guides/angular-change-detection.md)
 - [Guide - Data Handling with Mappers](./guides/data-handling-with-mappers.md)

docs/guides/icm-http-error-mapping.md

@@ -0,0 +1,26 @@
+<!--
+kb_guide
+kb_pwa
+kb_everyone
+kb_sync_latest_only
+-->
+
+# ICM HTTP Error Mapping
+
+The ICM provides a big variety of different REST resources managed by various teams and services.
+As the maturity of resources varies, so does the format of HTTP errors provided by those endpoints.
+The classic error response was submitted via HTTP headers and slowly the new format of providing even localized messages in the body of an error is being implemented.
+For the PWA this means that potentially every service and component managing a different resource has to handle different formats.
+In version 0.23 of the PWA we refactored the error handling to provide a consistent simplified format for all HTTP errors throughout the application.
+
+## Implementation
+
+Most of the work is done by the [HttpInterceptor](https://angular.io/api/common/http/HttpInterceptor) [ICMErrorMapperInterceptor][icm-error-mapper-interceptor].
+It converts responses with `error-key` headers, responses with `errors` body and also provides a fallback mapping for errors not matching this format.
+
+> :bulb: Mapping the [HttpErrorResponse](https://angular.io/api/common/http/HttpErrorResponse) is mandatory as the object itself is not serializable and should therefor not be pushed into the [State Management](../concepts/state-management.md)!
+
+If necessary, you can provide a custom [SPECIAL_HTTP_ERROR_HANDLER][icm-error-mapper-interceptor] for a specific use case.
+All custom mappers should be provided in the [ConfigurationModule](../../src/app/core/configuration.module.ts).
+
+[icm-error-mapper-interceptor]: ../../src/app/core/interceptors/icm-error-mapper.interceptor.ts

docs/guides/migrations.md

@@ -14,6 +14,10 @@ We removed deprecated exports related to the NgRx testing refactorings introduce
 We switched our main development to the new headless REST application type provided by ICM 7.10.21.0.
 If you are upgrading and want to continue using the Responsive Starter Store application types, do not cherry-pick the [commits that switch application types](https://github.com/intershop/intershop-pwa/compare/a63d2a2fc1ffdb404e6b1fe8ffb79310fa2ef60f...741454c8c839dd001a3943236172d75ffd05541d).
 
+We refactored the way ICM Http Errors are handled in the PWA.
+You can read about it [here](./icm-http-error-mapping.md).
+Tests emulating HTTP errors now have to use the helper function `makeHttpError` from [`ish-core/utils/dev/api-service-utils`](../../src/app/core/utils/dev/api-service-utils.ts).
+
 ## 0.20 to 0.21
 
 We deprecated and reworked the way of testing with NgRx.