Docs: Aktualisierung der Dokumentation für Task [31e88f42]

connector-superoffice/README.md

@@ -38,10 +38,18 @@ This directory contains Python scripts designed to integrate with the SuperOffic
     *   Before extensive processing, the worker now checks `connector_queue.db` via `queue_manager.check_for_recent_duplicate()`.
     *   If a `contact.created` event for the same company name is already `PROCESSING` or has been `COMPLETED` within the last 5 minutes, the current job is immediately `SKIPPED` as a duplicate.
 
+#### 💊 E. Job Stability (Poison Pill)
+*   **Problem:** API errors or transient issues could cause a job to enter an infinite retry loop, blocking the entire queue indefinitely.
+*   **Solution:** A **"poison pill" mechanism** was added to the queue manager.
+    *   A `retry_count` is now tracked for every job.
+    *   If a job fails and is retried, this counter is incremented.
+    *   If the counter exceeds a maximum threshold (currently 5), the job is automatically moved to the `FAILED` state and will not be retried again. This ensures that problematic jobs are cleared and do not block new incoming events.
+
 ### 3. Advanced API Handling (Critical Fixes)
 
 *   **OData Pagination:** We implemented `odata.nextLink` support (Manuel Zierl's advice) to correctly handle large result sets (>1000 records).
 *   **Case Sensitivity:** We learned that SuperOffice API keys are case-sensitive in responses (e.g., `contactId` vs `ContactId`) depending on the endpoint. Our code now handles both.
+*   **Robust Authentication:** The API client was hardened to raise exceptions on authentication failures instead of returning `None`. This ensures that auth errors are properly caught and jobs are failed or retried correctly.
 *   **Auth Consistency:** Always use `load_dotenv(override=True)` to prevent stale environment variables (like expired tokens) from lingering in the shell process.
 *   **Identity Crisis:** The `Associate/Me` and `Associate/{id}` endpoints return 500 errors if the API user lacks a linked Person record. This is a known configuration blocker for automated mailing.