# Error codes

Every API error is a JSON body with `code`, `error`, `hint` and `retryable`. Codes are stable; a client may switch on them. This page lists the ones an integration is most likely to meet.

## Request and auth

- `bad_json` - the body is not valid JSON. Fix the body.
- `validation` - a field is missing or invalid. The `hint` names the field.
- `bad_id` - a path or body identifier is not a UUID.
- `token_expired` - the API key passed its `expires_at`. Create a new key.
- `forbidden` - the key or member lacks the scope named in `hint`.
- `not_found` - the resource does not exist in this workspace.

## Sending

- `suppressed` - the recipient is on the suppression list. Remove it only with the recipient's consent.
- `newsletter_consent_missing` - a newsletter send needs a newsletter channel grant. Import the address as active or complete double opt-in.
- `consent_withdrawn` - the recipient opted out. Do not send again.
- `impressum_incomplete` - a marketing send needs the legal sender fields (street and city).
- `route_kind_mismatch` - a newsletter must use the `broadcast` route, transactional mail uses `outgoing`.
- `safe_mode` - the workspace or project is in the sandbox and the recipient is not a simulator or allowlisted address.
- `content_blocked` - the content gate refused the message. The response carries the reasons.
- `scanner_unavailable` - the spam filter is unreachable, so marketing is refused; retry later. Transactional mail keeps running.
- `send_failed` - the provider did not accept the message; the hint says whether a retry helps.

## Agent keys

- `recipient_not_allowed` - the recipient is outside the key's allowlist.
- `approval_required` - the recipient count is above the key's threshold. A human must approve, and the `approval.required` event fires.
- `token_daily_cap_reached` - the key reached its daily cap. It resets at midnight UTC.

## Idempotency

- `idempotency_key_reuse` - the same key was used with a different body. Use a new key for a new request.
- `idempotency_in_progress` - the first request with this key is still running. Retry after `Retry-After`.

## Inbound and forwarding

- `attachments_not_supported` - attachments are not accepted; the sender gets a notice.
- `inbound_message_truncated` - reserved for setups with raw storage; the message was larger than the receiving path can read.

`retryable: true` means the same request may succeed later. `retryable: false` means retrying unchanged will fail again.