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.

This page is the developer-oriented reference for the problem-type URIs and the NotFoundError class hierarchy. For the response surface and content negotiation an API consumer sees, see the Error Reference.

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>.

Controller error re-mapping¶

Class metadata is the single source of truth for the wire contract; a controller MUST NOT catch a domain error and re-raise it with a different HTTP status or error_code. Doing so drops the originating error's retryable signal and its discriminating code (see ADR-0014).

• Business-rule vs transient-backend. When one call site can fail for a business reason or a transient backend reason, raise a distinct typed error for the business case so the contract reflects the cause. The checkpoint service raises CheckpointActiveConflictError (409, non-retryable) when rejecting a delete/deploy of the active checkpoint, while a transient QueryError (500, retryable) flows to handle_persistence_error untouched. Controllers must not collapse the transient QueryError into the 409.
• Let retryable upstream failures propagate. oauth.py does not catch TokenExchangeFailedError; its 502 + retryable metadata propagates so the client learns the upstream token endpoint failed and may retry.
• Intentional uniform-404 (security override). connections.reveal_secret raises SecretRetrievalNotFoundError (404, RESOURCE_NOT_FOUND) for both "connection absent" and "secret absent". Returning the same 404 either way prevents a caller from enumerating which connection names exist by probing secret-reveal error codes. This uniform-404 is deliberate; do not "fix" it into a more specific code, which would re-introduce the enumeration leak.

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 message. On 5xx, handlers return the class-level default_message so no internal detail leaks. On 4xx, _select_message (and the handle_validation_error / handle_http_exception / handle_invalid_cursor handlers) routes the exception message through scrub_secret_tokens as a defence-in-depth pass: a credential or token a raise site interpolated is redacted, while ordinary validation text is untouched. This central scrub is why domain errors propagate straight to handle_domain_error with no controller-level catch-and-sanitise. Several Litestar-side handlers go further and 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¶

The check_domain_error_hierarchy.py gate that enforces this rule (no stdlib-rooted exception subclasses under src/synthorg/) is documented in Convention Gates.

Error-code uniqueness gate¶

Each ErrorCode maps to exactly one DomainError subclass, so a client branching on error_code can always tell two conditions apart. The one exception is an inheritance alias: a subclass that deliberately keeps an ancestor's code (for example ProviderModelNotFoundError, which subclasses ModelNotFoundError and inherits MODEL_NOT_FOUND 3011, and the NotFoundError subclasses that share RESOURCE_NOT_FOUND 3000 as the fallback). Two unrelated classes declaring the same code is a violation.

scripts/check_error_code_uniqueness.py enforces this at pre-push and in CI. For each concrete DomainError subclass it collects the (class, error_code, bases) triple by AST across every *.py file under src/synthorg/ (subclasses can live in any module, not only errors.py), groups by code, and fails a group unless its members share a common DomainError ancestor declaring that code, or the code is one of the shareable generic codes (INTERNAL_ERROR, VALIDATION_ERROR, RESOURCE_NOT_FOUND, RESOURCE_CONFLICT, RECORD_NOT_FOUND, ...). The gate is AST-only (no import), uses git-ls-files discovery with a Path.rglob fallback, and ships with zero offenders.

Per-line opt-out (reserved for documented twin classes that legitimately share a code, e.g. a persistence-layer mirror of a domain error):

class PersistenceVersionConflictError(QueryError):  # lint-allow: error-code-uniqueness -- twin of domain VersionConflictError
    ...

The justification after -- is mandatory. See ADR-0014 for the rationale and the four duplicate-code pairs this gate locked down.

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¶

The broad-handler rule for propagating MemoryError / RecursionError via synthorg.core.critical_errors.reraise_critical is documented in Async concurrency conventions.

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