feat: add field-level error handling to HttpClientException

- Extended HttpClientException to capture and expose field-level validation errors from PROFFIX API responses
- Added methods to check for, retrieve, and format field-specific error details (hasFieldErrors, getFieldErrors, getDetailedMessage)
- Updated README with comprehensive error handling examples and documentation

Author: pitw

CHANGELOG.md

@@ -0,0 +1,61 @@
+# Changelog
+
+Alle wichtigen Änderungen an diesem Projekt werden in dieser Datei dokumentiert.
+
+Das Format basiert auf [Keep a Changelog](https://keepachangelog.com/de/1.0.0/),
+und dieses Projekt folgt [Semantic Versioning](https://semver.org/lang/de/).
+
+## [2.1.0] - 2025-11-12
+
+### Hinzugefügt
+
+- **Erweitertes Error Handling**: Feldspezifische Validierungsfehler werden jetzt erfasst und können über die `HttpClientException` abgerufen werden
+  - Neue Methode `hasFieldErrors()`: Prüft, ob feldspezifische Fehler vorhanden sind
+  - Neue Methode `getFieldErrors()`: Gibt ein Array mit allen Feldfehlern zurück
+  - Neue Methode `getDetailedMessage()`: Gibt eine formatierte Nachricht mit allen Fehlerdetails zurück
+  - Feldvalidierungsfehler enthalten `Name`, `Message` und `Reason` für jeden Fehler
+- **Dokumentation**: Umfassende Error-Handling-Dokumentation in `docs/ERROR_HANDLING.md`
+- **Beispiele**: Neues Beispiel `examples/error_handling_example.php` zur Demonstration der Error-Handling-Features
+- **SessionCache-Dokumentation**: Technische Details zur `SessionCache`-Klasse im README hinzugefügt
+
+### Geändert
+
+- `HttpClientException` erweitert um optionalen `$fieldErrors`-Parameter
+- `HttpClient::lookForErrors()` extrahiert jetzt `Fields`-Array aus PROFFIX API Fehlerantworten
+- README aktualisiert mit Error-Handling-Sektion und SessionCache-Details
+
+### Technische Details
+
+Die PROFFIX REST API gibt bei Validierungsfehlern ein `Fields`-Array zurück, das bisher ignoriert wurde. Jetzt werden diese Details erfasst und können programmatisch abgerufen werden:
+
+```php
+try {
+    $response = $client->post('ADR/Adresse', $data);
+} catch (HttpClientException $e) {
+    if ($e->hasFieldErrors()) {
+        foreach ($e->getFieldErrors() as $error) {
+            echo "{$error['Name']}: {$error['Message']}\n";
+        }
+    }
+}
+```
+
+## [2.0.0] - 2024
+
+### Hinzugefügt
+
+- Session-Caching-Funktionalität zur Performance-Verbesserung
+- `SessionCache`-Klasse für dateibasiertes Session-Management
+- Automatische Session-Wiederverwendung über mehrere Requests
+- Plattformspezifische Cache-Verzeichnisse (Windows/Linux/Mac)
+- Option `enable_session_caching` zum Aktivieren/Deaktivieren des Cachings
+
+### Geändert
+
+- PHP-Mindestversion auf 8.2 erhöht
+- `HttpClient` nutzt jetzt Session-Caching standardmäßig
+- Automatische Cache-Invalidierung bei 401-Fehlern
+
+## [1.x.x] - Frühere Versionen
+
+Siehe Git-Historie für Details zu früheren Versionen.

CHANGELOG_SESSION_CACHING.md

@@ -88,6 +88,17 @@ Der Wrapper unterstützt automatisches Session-Caching, um die Performance zu ve
 
 Der Dateiname wird aus Benutzername, Datenbank und URL generiert, um Konflikte bei mehreren Clients zu vermeiden.
 
+**Technische Details:**
+
+Die Session-Verwaltung erfolgt über die `SessionCache`-Klasse (`src/RestAPIWrapperProffix/HttpClient/SessionCache.php`), die folgende Funktionen bietet:
+
+- `load()`: Lädt eine gespeicherte Session-ID aus dem Cache
+- `save($sessionId)`: Speichert eine Session-ID im Cache
+- `clear()`: Löscht die gespeicherte Session-ID
+- Automatische Erkennung des plattformspezifischen Cache-Verzeichnisses
+- Thread-sichere Dateioperationen mit `LOCK_EX`
+- Kollisionsvermeidung durch Base64-URL-kodierte Dateinamen
+
 **Session-Caching deaktivieren:**
 
 ```php
@@ -202,6 +213,76 @@ $dbInfo = $pxrest->database();
 
 Alle Methoden geben die Response als Array bzw. `NULL` (z.B. bei `DELETE`) zurück. Bei Fehlern wird eine `HttpClientException` mit der Rückmeldung der PROFFIX REST-API geworfen.
 
+### Error Handling
+
+Der Wrapper bietet erweitertes Error Handling, das sowohl allgemeine Fehlermeldungen als auch feldspezifische Validierungsfehler erfasst.
+
+#### Beispiel einer PROFFIX API Fehlerantwort
+
+```json
+{
+  "Fields": [
+    {
+      "Reason": "EMPTY",
+      "Name": "PLZ",
+      "Message": "PLZ darf nicht leer bleiben!"
+    },
+    {
+      "Reason": "EMPTY",
+      "Name": "Land",
+      "Message": "Land darf nicht leer bleiben!"
+    }
+  ],
+  "Message": "Mindestens ein Feld ist ungültig."
+}
+```
+
+#### Fehlerbehandlung mit HttpClientException
+
+```php
+use Pitwch\RestAPIWrapperProffix\HttpClient\HttpClientException;
+
+try {
+    $data = ["Ort" => "Zürich", "PLZ" => "", "Land" => ""];
+    $neueAdresse = $pxrest->post("ADR/Adresse", $data);
+} catch (HttpClientException $e) {
+    // Hauptfehlermeldung
+    echo "Fehler: " . $e->getMessage() . "\n";
+    // "Mindestens ein Feld ist ungültig."
+    
+    // Prüfen, ob feldspezifische Fehler vorhanden sind
+    if ($e->hasFieldErrors()) {
+        echo "Feldvalidierungsfehler:\n";
+        
+        foreach ($e->getFieldErrors() as $error) {
+            echo sprintf(
+                "  - %s: %s (Grund: %s)\n",
+                $error['Name'],
+                $error['Message'],
+                $error['Reason']
+            );
+        }
+        
+        // Oder alle Details als formatierte Nachricht
+        echo "\n" . $e->getDetailedMessage();
+    }
+}
+```
+
+**Verfügbare Methoden:**
+
+- `getMessage()`: Gibt die Hauptfehlermeldung zurück
+- `hasFieldErrors()`: Prüft, ob feldspezifische Fehler vorhanden sind
+- `getFieldErrors()`: Gibt ein Array mit allen Feldfehlern zurück
+- `getDetailedMessage()`: Gibt eine formatierte Nachricht mit allen Fehlerdetails zurück
+- `getCode()`: Gibt den HTTP-Statuscode zurück
+- `getRequest()`: Gibt das Request-Objekt zurück
+- `getResponse()`: Gibt das Response-Objekt zurück
+
+Weitere Details und Beispiele finden sich in der [Error Handling Dokumentation](docs/ERROR_HANDLING.md).
+
+### Zusatzinformationen zur Response
+
 Zudem lassen sich Zusatzinformationen zur letzten Response wie folgt ausgeben:
 
 ### Letzter Request

README.md

@@ -0,0 +1 @@
+2.1.0