14 - Fehlerbehandlung & Logging¶

Dokument: Error-Handling-Architektur Stand: 28.02.2026 Scope: Frontend-Errors, Backend-Logging, Recovery Status: Audit-ready

1. Error-Logging-System¶

1.1 Frontend-Error-Logger¶

Datei: lib/useErrorLogger.ts (~160 Zeilen)

Hook: useErrorLogger(walletAddress?, userEmail?) Standalone: logErrorStandalone(params) (ohne Hook-Kontext)

1.2 Session-Tracking¶

Eindeutige Session-ID pro Browser-Session
Gespeichert in sessionStorage
Ermöglicht Korrelation mehrerer Fehler einer Session

1.3 Log-Endpoint¶

Endpoint: POST /api/log-error

Request:

{
  "walletAddress": "0x...",
  "userEmail": "user@example.com",
  "sessionId": "uuid",
  "errorCode": "INSUFFICIENT_BALANCE",
  "errorMessage": "Not enough USDT",
  "errorStack": "Error: ...\n  at ...",
  "action": "BUY_TICKET",
  "context": { "poolId": 2, "tipCount": 5 },
  "intentId": "uuid",
  "txHash": "0x..."
}

Response:

{ "ok": true, "errorId": 42, "errorCode": "INSUFFICIENT_BALANCE" }

1.4 Error-Actions¶

Action	Beschreibung
`LOGIN`	Login-Versuch
`BUY_TICKET`	Ticket-Kauf
`SIGN_PERMIT`	Permit-Signierung
`APPROVE_USDT`	USDT-Approval
`SUBMIT_TX`	TX-Submission
`SEND_TOKEN`	Token-Transfer
`REFRESH_BALANCE`	Balance-Aktualisierung
`UNKNOWN`	Nicht kategorisiert

1.5 Automatische Error-Code-Erkennung¶

Pattern-Matching auf Error-Messages:

Pattern	Error-Code
"previous day not settled"	`PREVIOUS_DAY_NOT_SETTLED`
"insufficient balance"	`INSUFFICIENT_BALANCE`
"insufficient allowance"	`INSUFFICIENT_ALLOWANCE`
"user rejected" / code 4001	`USER_REJECTED`
"permit expired"	`PERMIT_EXPIRED`
"nonce already used"	`NONCE_ALREADY_USED`
"reverted"	`TX_REVERTED`
"gas estimation failed"	`GAS_ESTIMATION_FAILED`
"network" / "fetch"	`NETWORK_ERROR`

1.6 Nicht geloggte Fehler¶

User-Ablehnungen werden NICHT geloggt: - Signatur abgelehnt (Code 4001) - Modal geschlossen - Login abgebrochen

2. Buy-Flow-Fehlerzustände¶

2.1 Pre-Flight-Fehler¶

Error-State	Trigger	User-Aktion
`error_balance`	USDT-Guthaben zu niedrig	Balance aufladen
`error_unsettled`	Vorheriger Tag nicht settled	Warten
`error_limit`	Spending-Limit erreicht	Limit anpassen oder warten
`error_self_excluded`	Self-Exclusion aktiv	Warten bis Ablauf
`error_tx_in_progress`	Andere TX läuft (409)	Warten oder Resume

2.2 Runtime-Fehler¶

Error-State	Trigger	Recovery
`signature_cancelled`	User lehnt Signatur ab	Reset, erneut versuchen
`error_rejected`	Approval fehlgeschlagen	Reset
`error_no_gas`	Kein ETH für Approval	Gas-Faucet
`error_allowance`	Allowance-Problem	Revoke + neu approven
`error_network`	Netzwerkfehler	Resume-Intent
`error_timeout`	30s Bestätigungs-Timeout	Resume-Intent
`error_expired`	Permit abgelaufen	Neuen Intent erstellen

2.3 Confirmation-Polling¶

Timeout: 30 Sekunden
Polling-Intervall: 1 Sekunde
Fallback: Stündliches Polling nach Timeout
Max-Retries: Unbegrenzt (stündlich)

3. Claim-Flow-Fehlerzustände¶

Fehler	Beschreibung	Recovery
Signatur abgelehnt	User cancelled EIP-712	Erneut versuchen
Unzureichende Balance	Nicht genug für Gas	Balance aufladen
KYC erforderlich	Schwellenwert überschritten	KYC durchführen
Rate Limiting	Zu viele Claims	Warten
Merkle-Proof ungültig	Daten-Inkonsistenz	Support kontaktieren
TX reverted	Contract-Fehler	Debug-Endpoint prüfen

4. Error-Boundaries (React)¶

4.1 Implementierte Boundaries¶

Boundary	Datei	Scope
Root	`[locale]/error.tsx`	Alle Seiten
Dashboard	`dashboard/error.tsx`	Dashboard-Seite
Claim	`claim/error.tsx`	Claim-Seite

4.2 Verhalten¶

export default function Error({ error, reset }: { error: Error, reset: () => void }) {
  // Fehler anzeigen
  // Retry-Button → reset()
}

5. Loading States¶

Seite	Datei	Beschreibung
Play	`play/loading.tsx`	Skeleton-Platzhalter
Dashboard	`dashboard/loading.tsx`	Skeleton-Platzhalter

Skeleton-Komponente: app/components/Skeleton.tsx - Shimmer-Animation - Konfigurierbare Dimensionen - Muted Colors

6. Netzwerk-Fehlerbehandlung¶

6.1 Online/Offline-Erkennung¶

Hook: useOnlineStatus Komponente: OfflineBanner

Offline → Banner anzeigen, Aktionen blockiert
Online  → Banner ausblenden, Aktionen freigegeben

6.2 Maintenance-Modus¶

Hook: useMaintenanceStatus Komponente: MaintenanceBanner

Polling: GET /api/maintenance alle 30 Sekunden
Maintenance → Banner anzeigen, Käufe blockiert

6.3 RPC-Fehler¶

Situation	Handling
Balance-Fetch fehlgeschlagen	Letzte bekannte Balance beibehalten
Provider-Disconnect	Session-Wiederherstellung versuchen
TX-Confirmation Timeout	Resume-Intent-Mechanismus

7. Recovery-Mechanismen¶

7.1 Intent-Recovery¶

Seiten-Reload während Kauf
  → Intent-ID aus State laden
  → POST /api/buy/resume-intent
  → Status abfragen
  → Flow an korrekter Stelle fortsetzen

7.2 Session-Recovery¶

App-Start
  → Web3Auth prüft Session
  → Provider-RPC Polling (max 5s)
  → loadUserDataWithRetry (max 4 Versuche, exponentielles Backoff)

7.3 Wallet-Wiederherstellung¶

Firefox-Bug erkannt
  → Sofortiger Logout
  → Wallet-Storage löschen
  → Fehler anzeigen
  → User muss neu einloggen

8. Claim-Event-Logging¶

Datei: lib/claimEventLogger.ts

Dediziertes Logging für Claim-Operationen:

Event-Typ	Scope	Beschreibung
`CLAIM_SIGNATURE_ERROR`	winner/affiliate	Signatur-Fehler
`CLAIM_TX_ERROR`	winner/affiliate	TX-Fehler
`CLAIM_PENDING_SET`	mixed	Optimistic Update
`CLAIM_TX_REVERTED`	mixed	TX reverted
`CLAIM_CONFIRMED`	mixed	Claim erfolgreich
`BACKFILL_TRIGGERED`	system	Backfill gestartet
`BACKFILL_CLAIM_CONFIRMED`	system	Backfill erfolgreich

DB-Tabelle: claim_events(event_type, scope, tx_hash, details)

9. NotificationQueue¶

Komponente: app/components/NotificationQueue.tsx

Feature	Beschreibung
Queue-Management	FIFO
Auto-Dismiss	Konfigurierbar
Typen	Success, Error, Info
Stacking	Gestapelte Anzeige

Weiterführende Dokumente: - 05 - Buy Flow - 06 - Claim Flow - 10 - Sicherheit