The Problem contract
Share safe error information while keeping transport and recovery decisions explicit.
Public fields
The common representation uses type, title, code, detail and optional traceId, instance and transport. Stable identifiers use urn:akkadia:problem:<encoded-code>. Classify by code, never by the prose in detail.
| Boundary | Contract |
|---|---|
| HTTP | application/problem+json; body status matches the actual 400–599 response |
| Socket | Public Problem inside the existing envelope; do not invent an HTTP status in the body |
| Local application | Problem information without a fabricated HTTP response status |
| Command result | Existing typed result envelope, not a global fatal error |
Legacy socket envelopes may keep an outer status for compatibility. New consumers do not depend on that field. Native connection failures still belong to connection establishment.
Safe serialization
publicProblem chooses safe fallback guidance. Stack traces, causes, raw messages and metadata belong in separate private diagnostics. HTTP logging and responses share a trace ID, also exposed as x-trace-id.
parseProblemDetails accepts supported bodies and legacy envelopes, validates fields and copies only allowed data. readHttpProblem also handles empty or HTML HTTP failures. Parsing remote text does not automatically make it suitable for a user-facing message.
Recovery is owned by the operation
Authentication/session admission and missing or failed rooms may require disconnection. Ordinary rejected commands, HTTP 4xx responses and unknown codes do not automatically end a session. The owning server can still close an unrecoverable connection explicitly.
Never blindly retry crafting, reward claims or chain mutations. Confirm receipts and authoritative state first. The shared Axios requester still throws the original Axios error for compatible consumers; adapters extract its Problem information.
Compatibility
Keep AppError as an internal exception representation and native exceptions inside implementations where appropriate. Normalize at presentation and transport boundaries. Deploy clients and servers together when changing their public error contract; an uncoded legacy response uses a safe fallback, not message-string matching.
The field model follows Problem Details conventions. Socket and app objects reuse that information model; they are not HTTP responses merely because their fields resemble one.
Standard reference
Problem Details for HTTP APIs (RFC 9457) defines the HTTP information model and replaces RFC 7807. Akkadia adds application extensions such as code, traceId and transport. The standard’s HTTP semantics do not turn socket or local-app errors into HTTP responses.