Errors and limits

Error shape

Failed requests return JSON:

{
  "code": "content_blocked",
  "error": "message blocked by the content gate",
  "hint": "Remove promotional phrasing or send on the broadcast route after DOI.",
  "retryable": false
}

hint is safe to show in a UI. Do not parse error for control flow. Use code. retryable is true for every 5xx and for 429.

HTTP status

Method mismatches

A method mismatch keeps the authoritative Allow header and adds a parseable body:

{
  "code": "method_not_allowed",
  "error": "Method GET not allowed on /api/projects",
  "hint": "Allowed: POST"
}

Error-code vocabulary

retryable tells an agent whether to stop or to wait and resend. Prefer an Idempotency-Key on any retry of a write.

Exact strings can grow; treat unknown codes as generic failures and show hint. The same vocabulary is available machine-readably in the OpenAPI document as x-error-codes (see https://werkmail.eu/openapi.yaml).

Idempotency

Idempotency-Key (or X-Idempotency-Key) on single send, and idempotency_key on batch items / bulk, replay the original status and body for the same workspace + key. Keys are scoped per tenant.

The key is claimed atomically before any work starts, so two parallel requests with the same key can never both send:

• A concurrent duplicate waits up to a few seconds for the first request. If that one is still running, it gets 409 idempotency_in_progress (retryable: true, Retry-After: 2). Send the same request again with the same key and you get the stored result.
• The same key with a different body returns 422 idempotency_key_reuse.
• Failed attempts are not stored, so the same key can be retried. An attempt that crashed mid-way expires after 2 minutes.
• Keys are honoured for 24 hours and then purged.

A replay is marked explicitly and does not resend:

{
  "message_id": "m-…",
  "id": "…",
  "status": "processed",
  "idempotent": true
}

Success needs evidence

A send is only accepted when the response is 202 and carries a verifiable handle — message_id, id, and the scanner echo. A bare 200 with an empty body is never a successful send. If a send cannot be performed, the API returns a 4xx/5xx {code,error,hint} envelope instead. This holds for every token type (project and team), every message kind, and every send endpoint.

Poll GET /api/emails/{id} with the returned id to follow the status after a send; webhooks stay optional.

Rate limits

Werkmail applies a per-tenant client limiter in addition to the outbound platform. Bursting thousands of un-idempotent POSTs will 429. Prefer batch/bulk and backoff on 429.

Every 429 response carries a Retry-After header with the number of seconds to wait before resending. The value comes from the limiter or cap that fired:

When the exact wait is unknown the header is 60. Honour the larger of Retry-After and your own backoff.

HTTP bodies are capped at MaxMessageRequestBytes (tens of MiB) so a single request cannot exhaust the process.