Troubleshooting & Recovery
Here you check when you can safely continue on your own and when you must stop and hand off the work to a human.
Owner code is missing or invalid
Section titled “Owner code is missing or invalid”If the owner email is missing, expired, suppressed, or the code is no longer valid after failed attempts, request exactly one fresh code via POST /owner-otp/resend. Use the installation key from /organizations for this.
If owner_otp_delivery.status: "suppressed", stop the agent flow and hand off to a human. Repeated resend without clarification is not a recovery path.
Agent email code is missing or invalid
Section titled “Agent email code is missing or invalid”If agent_email has been set and the agent email code is missing or expired, request a fresh code via POST /agent-otp/resend.
Then use the new agent_otp_delivery.correlation_id. Search the agent mailbox for the subject fragment Ref: <correlation_id> and read the code from the standalone body line Code: <OTP>.
Installation key lost
Section titled “Installation key lost”Plaintext installation keys are not displayed again. If the installation key from /organizations or a freshly rotated key is lost, stop.
There is intentionally no self-service path that recovers a lost installation key. Do not simply bootstrap a second organization as a replacement. Hand off to the responsible owner and webRichtung so that the organization, wallet, and audit chain are preserved.
HTTP 412 in first-run flow
Section titled “HTTP 412 in first-run flow”GET /org/current before successful owner claim may respond with HTTP 412 precondition_failed. If agent_email has been set, the same applies before successful agent email verification. This is expected behavior: the required authorization is still missing.
The next step is not retry spam. Wait for the missing code, call POST /owner-otp/claim or POST /agent-otp/verify, and only use /org/current as a status read after that. /keys/rotate is also blocked before these OTPs. Operational /mcp/dry_run and /mcp/invoke calls remain additionally blocked until activation by webRichtung. The complete error rule is in the error taxonomy.
Activation remains pending
Section titled “Activation remains pending”After owner claim and optional agent email verification, the agent polls GET /org/current:
- first poll after 30 seconds
- then at most once per 60 seconds
- maximum 15 minutes
If installation.operator_approval_status remains pending after that, stop the flow and hand off to the responsible human. If blocked, stop immediately.