Error Codes¶

Three systems produce error codes: the API, SMTP (Postfix), and Rspamd. This page covers all of them.

API Error Codes¶

HTTP Status Codes¶

API Response Format¶

Success responses are typed per endpoint (Pydantic response models) — there is no single success envelope. Helper-built responses look like:

{
  "type": "success",
  "msg": "Human-readable message",
  "data": { "...": "optional payload" }
}

Error responses share one envelope. A custom exception handler in the api service strips FastAPI's usual detail wrapper:

{
  "type": "error",
  "msg": "Error description",
  "error_code": "MAILBOX_ALREADY_EXISTS",
  "correlation_id": "..."
}

• type and msg are always present.
• error_code is a stable machine-readable identifier, present only on the subset of errors that carry one (see the table below).
• correlation_id is injected by middleware into every JSON error body (status ≥ 400) and echoed in the X-Correlation-Id response header — quote it when reporting problems.
• Validation failures (422) from FastAPI itself still use the framework's {"detail": [...]} shape.

Other worker services (tracking, rag, monitoring, webhooks, …) have their own ad-hoc shapes — most emit FastAPI's default {"detail": "..."}.

Stable error_code Values¶

These are the machine-readable codes the API actually emits (the casing really is mixed):

A replayed idempotent request returns the original response with the header Idempotency-Replayed: true.

SMTP Status Codes¶

SMTP uses 3-digit codes. The first digit indicates the category.

2xx — Success¶

4xx — Temporary Failure (will retry)¶

5xx — Permanent Failure (won't retry)¶

Enhanced Status Codes (DSN)¶

DSN codes are 3-part codes (x.y.z) that give more detail. The first digit mirrors the SMTP category.

Class 2.x.x — Success¶

Class 4.x.x — Temporary Failure¶

Class 5.x.x — Permanent Failure¶

Rspamd Action Codes¶

Rspamd assigns a score and takes an action based on configured thresholds. The thresholds actually shipped (mailer/rspamd/config/local.d/actions.conf):

Actions¶

Per-organization overrides from the settings.spam_policy sync can replace these thresholds for a tenant's domains.

Common Rspamd Symbols¶

Symbol scores are Rspamd's stock defaults (Mailyte doesn't override individual symbol scores), plus the Mailyte-specific multimap symbols with fixed scores:

Postfix Rejection Codes¶

These appear in the Postfix log as NOQUEUE: reject: