Errors and troubleshooting
Start with the request ID, the operation that failed, and the boundary responsible for it. Redact tokens, passwords, TOTP seeds, passkey payloads, invitation links and private evidence before sharing diagnostics.
| Symptom | Likely boundary | Next check |
|---|---|---|
| Authorization callback has wrong state or nonce | Application login transaction | Discard the attempt and start again from /login; never replay a callback URL. |
| Code exchange fails | Client and issuer | Confirm exact redirect, original PKCE verifier, one-use code, client secret where required, and issuer discovery. |
| Token rejected by management | API authentication | Check signed issuer, taifa-management audience, expiry and JWKS; an ID token will not work. |
403 after a valid login | Governance or product access | Check current Person, Institution, project, local account and role. |
409 on mutation | Review or idempotency state | Compare request body and key, current approval, version and issuer binding. |
| Lifecycle gate closes | Product consumer | Check dedicated signature, ordered cursor, receipt head, freshness and snapshot recovery. |
| Mail request is pending or ambiguous | Delivery worker | Poll the saved provider ID and reconcile before resubmission. |
| Owned issuer will not start | Release gate | Confirm disposable loopback mode, database name, exact portal client and required keys. Production startup is disabled. |
Management response shapes
Most management failures use {"detail":"..."}. Validation failures can return structured entries in detail. The API includes X-Request-ID in responses. Preserve it with the HTTP status and route, then inspect the exact schema in management API. Do not parse the human detail string as a stable machine error code.
Repeat safely
A human mutation’s Idempotency-Key is scoped to actor and request content. Retry the same key with the same body after an uncertain response. A changed body with the same key returns 409. Product installation and acknowledgement should also be idempotent, but use the exact lifecycle entity version or link binding as the unit of work. When authority freshness expires, restore connectivity and catch up before reopening protected access.