Fehlerbehebung & Recovery
Diese Seite beschreibt, wann ein Agent selbst sauber fortsetzen darf und wann er stoppen muss.
Owner-Code fehlt oder ist ungültig
Abschnitt betitelt „Owner-Code fehlt oder ist ungültig“Wenn die Owner-Mail fehlt, abgelaufen ist, unterdrückt wurde oder der Code nach Fehlversuchen nicht mehr gültig ist, fordere genau einen frischen Code über POST /owner-otp/resend an. Verwende dafür den Installation-Key aus /organizations.
Bei owner_otp_delivery.status: "suppressed" stoppst du den Agent-Flow und übergibst an einen Menschen. Wiederholtes Resend ohne Klärung ist kein Recovery-Pfad.
Agent-Mail-Code fehlt oder ist ungültig
Abschnitt betitelt „Agent-Mail-Code fehlt oder ist ungültig“Wenn agent_email gesetzt wurde und der Agent-Mail-Code fehlt oder abgelaufen ist, fordere einen frischen Code über POST /agent-otp/resend an.
Verwende danach die neue agent_otp_delivery.correlation_id. Suche in der Agent-Mailbox nach dem Betreffbestandteil Ref: <correlation_id> und lies den Code aus der eigenständigen Body-Zeile Code: <OTP>.
Installation-Key verloren
Abschnitt betitelt „Installation-Key verloren“Klartext-Installation-Keys werden nicht erneut angezeigt. Wenn der Installation-Key aus /organizations oder ein frisch rotierter Key verloren ist, stoppe.
Es gibt bewusst keinen Selbstbedienungs-Weg, der einen verlorenen Installation-Key wiederherstellt. Bootstrappe nicht einfach eine zweite Organisation als Ersatz. Übergib an den verantwortlichen Owner und webRichtung, damit Organisation, Wallet und Audit-Kette erhalten bleiben.
HTTP 412 im Erstpfad
Abschnitt betitelt „HTTP 412 im Erstpfad“GET /org/current vor erfolgreichem Owner-Claim kann mit HTTP 412 precondition_failed antworten. Wenn agent_email gesetzt wurde, gilt dasselbe vor erfolgreicher Agent-Mail-Verifikation. Das ist erwartetes Verhalten: Die erforderliche Legitimation fehlt noch.
Der nächste Schritt ist nicht Retry-Spam. Warte auf den fehlenden Code, rufe POST /owner-otp/claim oder POST /agent-otp/verify auf und nutze /org/current erst danach als Status-Read. /keys/rotate ist vor diesen OTPs ebenfalls gesperrt. Operative /mcp/dry_run- und /mcp/invoke-Aufrufe bleiben zusätzlich bis zur Freischaltung durch webRichtung gesperrt. Die vollständige Fehlerregel steht in der Fehlertaxonomie.
Freischaltung bleibt pending
Abschnitt betitelt „Freischaltung bleibt pending“Nach Owner-Claim und optionaler Agent-Mail-Verifikation pollt der Agent GET /org/current:
- erster Poll nach 30 Sekunden
- danach höchstens einmal pro 60 Sekunden
- maximal 15 Minuten
Bleibt installation.operator_approval_status danach pending, stoppe den Flow und übergib an den verantwortlichen Menschen. Bei blocked stoppst du sofort.