113 — Failed-Messages

PartnerDesk nutzt Symfony Messenger für asynchrone Aufgaben (Notifications, Buchhaltungs-Sync, Outgoing-Webhooks, Email-Versand). Wenn ein Job auch nach mehrfacher Wiederholung scheitert, landet er im Failed-Transport — und ist im Superadmin sichtbar.

Wann landet eine Message im Failed-Transport?

Pro Job-Typ gibt es eine eigene Retry-Strategie:

Transport	Retries	Backoff
notifications	3	30 s → 5 min
accounting (lexoffice/easybill-Sync)	6	10 s → 1 h
webhooks (Outgoing)	5	5 s → 2 min (exponentiell)
async (allgemein)	3	60 s → 10 min

Erst nach Erschöpfen aller Retries: Message wandert in failed.

Wer kann zugreifen?

Nur Plattform-Admins (ROLE_PLATFORM_OWNER und ROLE_PLATFORM_ADMIN). Tenant-Admins haben keinen Zugriff — Failed-Messages sind oft tenantübergreifend zu lösen.

Superadmin-Sicht

Superadmin → „Failed-Messages" in der Sidebar.

Liste

Pro Eintrag:

Spalte	Inhalt
Klasse	Message-Class-Name (z. B. SyncAccountingCreditNoteMessage)
Anzahl Versuche	Wie oft wurde retried
Letzter Error	Exception-Class + Kurz-Message
Original-Transport	Aus welchem Transport (z. B. accounting)
Zeit	Wann der finale Fail passierte

Detail-View

Klick auf Eintrag → Modal mit:

• Body der Message (Argumente, IDs).
• Voller Stack-Trace des letzten Fehlers.
• Stamps (Symfony Messenger Meta-Daten):
  • ErrorDetails.
  • Redelivery (Retry-Counter).
  • SentToFailureTransport (Original-Receiver-Name).

Aktionen

Retry

„Erneut versuchen"-Button verschiebt die Message zurück in den Original-Transport. Sie wird vom Worker abgeholt und nochmals ausgeführt.

Sinnvoll wenn:

• Externe API war kurz offline.
• DB-Lock gelöst sich gelöst.
• Konfigurations-Fix passiert (z. B. fehlender API-Key nachgereicht).

Verwerfen

„Endgültig verwerfen"-Button löscht die Message aus dem Failed-Transport.

Sinnvoll wenn:

• Message ist veraltet (z. B. Payout wurde inzwischen anders verarbeitet).
• Fehler ist tatsächlich permanent (z. B. Partner wurde gelöscht).

Typische Failures

SyncAccountingCreditNoteMessage

• Ursache: lexoffice/easybill-API kurzzeitig down.
• Aktion: nach Provider-Recovery → Retry.

SendNotificationBatchMessage

• Ursache: SendGrid-API-Key abgelaufen.
• Aktion: API-Key in Email-Settings erneuern → Retry.

DispatchWebhookMessage

• Ursache: Tenant-Custom-Webhook-URL antwortet nicht (404, Timeout).
• Aktion: URL beim Tenant prüfen → Tenant fixt → Retry.
• Auto-Deactivate: nach 10 finalen Failures wird der Webhook-Endpoint automatisch deaktiviert (Schutz vor Endlos-Schleifen).

Verwandte Kapitel

• 110 — Plattform-Admin
• 111 — Health-Endpoints (Queue-Stagnation wird dort als degraded gemeldet)
• 131 — Outgoing-Webhooks

---

Technische Tiefen-Doku: ../024-phpstan-failed-messages.md, ../138-cursor-write-backoff.md