Errors & status codes

Ductor speaks one error vocabulary across both protocols. Internally, code returns domain error sentinels; the transport layer classifies each sentinel to a Connect/gRPC code, an HTTP status, and a stable machine-readable error code, then renders it as gRPC status details or RFC 9457 Problem JSON.

The mapping, end to end

Anything not recognized as a domain error falls back to CodeInternal / HTTP 500 / INTERNAL — infrastructure errors are never leaked verbatim to clients.

Problem JSON (REST)

REST clients receive an RFC 9457 application/problem+json document. The body is the ProblemDetail struct in transport/exec/common/errors/problem_json.go:

{
  "type": "https://errors.ductor.io/QUOTA_EXCEEDED",
  "title": "Usage quota exceeded",
  "status": 429,
  "detail": "daily routing quota exceeded",
  "instance": "/api/v2/routing/route",
  "error_code": "QUOTA_EXCEEDED",
  "trace_id": "4f1c…",
  "request_id": "018f…",
  "retryable": false
}

Some errors add domain enrichment fields:

Error code → HTTP status

The error catalog

Every wire code is registered in transport/exec/common/errors with a retryable flag and an operational severity (used for alerting and logging). The catalog is stable — codes and their semantics are part of the API contract.

An unregistered code falls back to critical severity, non-retryable.

Sentinel → Connect code → HTTP

Generic domain sentinels

Declared in domain/errors/errors.go. Subdomain files add many more (strategy, claim, tenant, eventsourcing, routing, connector, workflow…).

Structured error types

For rich errors, Ductor uses typed structs that wrap a sentinel via Unwrap(), so errors.Is(err, ErrNotFound) still works while callers can also errors.As the concrete type for its fields.

What gets exposed

The transport layer only exposes an error's message to clients when it is a domain error — either a known structured type or a registered sentinel (IsDomainError). Infrastructure errors (pgx, Redis, and other internals) classify as non-domain, so their messages are never returned; clients get a generic INTERNAL / 500 Problem JSON while the real cause is logged with a trace ID. This is what keeps internal details from leaking through the API.

Internal-error masking

An error-masking interceptor runs just before the status interceptor. Any error that resolves to Internal/Unknown has its message replaced with:

Internal error (ref: <8-hex>)

The ref is the first 8 hex characters of the SHA-256 of the original error message. The full error is logged server-side keyed by that same ref, so an operator can correlate a client's opaque reference to the real cause without ever putting it on the wire. Give clients the ref when they report a 500 — it's the join key back to the server log.