Error Code Reference¶

SynthOrg's REST API emits RFC 9457 Problem Details responses on every error path. Every response carries three machine-readable fields that clients can discriminate on:

• type: a stable URI describing the error category
• error_code: an integer in one of the ranges below
• error_category: the category name matching the URI slug

Clients should dispatch on error_code (most specific) and fall back to error_category for generic handling. Messages and titles are human-readable and may change without notice; the code is the contract.

Category URIs¶

Authentication (1xxx)¶

Validation (2xxx)¶

Not Found (3xxx)¶

The NotFound hierarchy is rooted at NotFoundError. Each resource has a dedicated subclass that pins the right ErrorCode as a ClassVar (for example TaskNotFoundError in synthorg.engine.errors, ConnectionNotFoundError in synthorg.integrations.errors, and ResourceNotFoundError in synthorg.core.domain_errors as the 3000 fallback). Controllers raise the subclass directly, or via require_resource_or_404(..., error_class=...), so the wire error_code is fixed by the class rather than a runtime argument.

All share the same type URI; the numeric code is the discriminator.

Conflict (4xxx)¶

Rate Limit (5xxx)¶

Budget Exhausted (6xxx)¶

Provider / Integration (7xxx)¶

Internal (8xxx)¶

Content negotiation¶

Clients that set Accept: application/problem+json receive a bare RFC 9457 body. Clients that accept application/json receive an ApiResponse envelope with error_detail carrying the same fields. See the API reference for per-route examples.

HTTP exception handler registration (MANDATORY)¶

Litestar resolves exception handlers by walking the raised exception's MRO; the first matching type in EXCEPTION_HANDLERS (src/synthorg/api/exception_handlers.py) wins. Domain error families register a single base-class handler (e.g. BackupError, PersistenceError, OntologyError) so every subtype maps to a structured response without falling through to the catch-all Exception: handle_unexpected (which would surface as a generic 500 without a domain-specific error_code).

Controllers MUST NOT catch a domain error and build their own Response(...) envelope. Raise the typed domain error (declaring status_code / error_code / error_category ClassVars on the class) and let handle_domain_error produce the RFC 9457 envelope. Enforced at pre-push by scripts/check_no_controller_response_for_domain_errors.py. Per-line opt-out: # lint-allow: controller-domain-response -- <reason>.

Each handler:

1. Calls _log_error(request, exc, status=...) for structured logging (WARNING for 4xx, ERROR + traceback for 5xx).
2. Returns _build_response(...) so the response carries the full RFC 9457 envelope (or bare application/problem+json body when the client asks for it).
3. Scrubs the upstream message on 5xx. 4xx behaviour varies: domain handlers like handle_backup_error and handle_domain_error pass a user-safe exception message through, while several Litestar-side handlers intentionally return fixed public messages (handle_record_not_found -> "Resource not found", handle_not_authorized -> "Authentication required", handle_permission_denied -> "Forbidden", handle_not_found -> "Not found"). When in doubt, mirror the nearest existing handler in exception_handlers.py.

When introducing a new domain error family:

1. Add the base class to EXCEPTION_HANDLERS mapped to a dedicated handle_<domain>_error function.
2. Use isinstance dispatch inside the handler to map subtypes to specific HTTP status codes (404, 409, etc.) before falling through to the structured 500 branch.
3. Register the entry above the catch-all Exception: handle_unexpected line in the dict; MRO ordering does not depend on dict insertion order, but readability does.
4. Add tests in tests/unit/api/test_exception_handlers.py covering each branch and a regression test for the catch-all.

Domain-error-hierarchy gate¶

scripts/check_domain_error_hierarchy.py enforces the rule at pre-push and in CI: every class definition under src/synthorg/ whose direct base is one of Exception / RuntimeError / LookupError / PermissionError / ValueError / TypeError / KeyError / IndexError / AttributeError / OSError / IOError is a violation unless the class itself reaches DomainError via another base.

Only the root of a stdlib-rooted chain is flagged; migrating the root to DomainError automatically corrects every descendant.

Per-line opt-out:

class TsaError(Exception):  # lint-allow: domain-error-hierarchy -- RFC 3161 internals; observability stays stdlib-rooted
    ...

The justification after -- is mandatory and must be non-empty. The gate also accepts a frozen baseline file (scripts/domain_error_hierarchy_baseline.txt) listing pre-existing violations a rollout has not yet reached. The baseline shrinks monotonically: any entry that no longer maps to a real violation is reported as drift, so the file cannot harbour stale rows.

Error-code constants - frontend integration (MANDATORY)¶

src/synthorg/core/error_taxonomy.py is the single source of truth for ErrorCode and ErrorCategory. The dashboard imports the same constants from web/src/api/types/error-codes.gen.ts, which is generated from the Python enums by scripts/generate_error_codes_ts.py.

When adding or renaming a code:

1. Edit src/synthorg/core/error_taxonomy.py.
2. Run uv run python scripts/generate_error_codes_ts.py and commit web/src/api/types/error-codes.gen.ts alongside the Python change.
3. Update any frontend call sites that newly want to discriminate on the code (import ErrorCode from @/api/types/errors and use the named member, never the raw integer).

The pre-push gate scripts/check_error_codes_ts_in_sync.py re-runs the generator and fails if the committed error-codes.gen.ts differs byte-for-byte from the freshly rendered output, so a backend code addition that forgets the regeneration step cannot land.

Frontend code MUST import error codes through @/api/types/errors (re-exported from the generated module). Inlining numeric error codes (e.g. error_code: 3000) is forbidden -- name-based discrimination keeps the web/ and src/synthorg/ sides in lockstep when codes are renumbered.

Interpreter-critical exception propagation¶

MemoryError and RecursionError are subclasses of Exception, so a broad except Exception: block silently swallows them unless the handler propagates them explicitly. Call synthorg.core.critical_errors.reraise_critical(exc) as the first statement of the broad handler:

from synthorg.core.critical_errors import reraise_critical

try:
    ...
except Exception as exc:
    reraise_critical(exc)
    logger.warning(EVENT, error_type=type(exc).__name__, ...)
    raise QueryError(msg) from exc

asyncio.CancelledError is not routed through this helper because it is a BaseException, not an Exception; a broad except Exception: block never catches it. See Async concurrency conventions for the surrounding pattern.

Further reading¶

• Design: security: the SEC-1 rules behind the categories
• REST API reference: per-route examples plus a worked content-negotiation walkthrough
• src/synthorg/core/error_taxonomy.py: the authoritative ErrorCategory / ErrorCode enums + RFC 9457 helpers
• src/synthorg/core/domain_errors.py: the DomainError base + concrete subclasses (NotFoundError, ConflictError, ValidationError, ...)
• src/synthorg/core/persistence_errors.py: the PersistenceError hierarchy
• src/synthorg/core/critical_errors.py: the reraise_critical helper for the broad-except idiom