---
description: Error codes backend ↔ frontend and i18n message keys
globs: backend/src/common/errors/**,frontend/src/components/shared/formatApiError.ts,frontend/messages/**
alwaysApply: false
---

# API errors & translations

## Adding a new error

1. Add code to `backend/src/common/errors/error-codes.ts`
2. Throw via `AppException` (or validation DTO with that code)
3. Add matching key under `errors` in **all three** message files:
   - `frontend/messages/en.json`
   - `frontend/messages/fa.json`
   - `frontend/messages/nl.json`
4. Frontend catch: `getUserFacingError(err, tErrors, t('fallbackKey'))`

## Validation field errors

Backend returns `{ success: false, error: { code, details: [{ field, code }] } }`.

Frontend maps `details[].code` through the `errors` namespace.

## Do not

- Throw Nest `BadRequestException('English sentence')` for user-facing errors.
- Show raw `error.message` or stack traces to users.
- Add English-only strings inline in components.