Классификация ошибок

Проект обязан использовать единую классификацию ошибок. Это обеспечивает одинаковое поведение UI и предсказуемость.

---

Категории

MUST

• Network/Connectivity — отсутствие сети, таймауты.
• Auth/Access — 401, 403, истекшая сессия, отсутствие прав.
• Not Found — 404 (ресурс не найден).
• Conflict — 409 (конфликт версий или повторная операция).
• Other — прочие и доменно-специфичные ошибки.

Это правило распространяется на:

• back-end API endpoints
• Next.js API endpoints

---

Единая модель ошибки

MUST

• Ошибка нормализуется в единый формат.
• UI работает только с этим форматом, а не с raw ошибкой.

Пример модели

export enum ErrorKind {
  Network = 'network',
  Auth = 'auth',
  NotFound = 'not_found',
  Conflict = 'conflict',
  Other = 'other'
}

export interface AppError {
  kind: ErrorKind;
  messageKey: string;
  status?: number;
  retriable?: boolean;
};

Пример нормализации

export function normalizeError(error: unknown): AppError {
  if (isNetworkError(error)) {
    return { kind: ErrorKind.Network, messageKey: 'errors.network', retriable: true };
  }

  if (isHttpError(error)) {
    if (error.status === HTTP_STATUS.Unauthorized || error.status === HTTP_STATUS.Forbidden) {
      return { kind: ErrorKind.Auth, messageKey: 'errors.auth', status: error.status };
    }
    if (error.status === HTTP_STATUS.NotFound) {
      return { kind: ErrorKind.NotFound, messageKey: 'errors.not_found', status: error.status };
    }
    if (error.status === HTTP_STATUS.Conflict) {
      return { kind: ErrorKind.Conflict, messageKey: 'errors.conflict', status: error.status };
    }
  }

  return { kind: ErrorKind.Other, messageKey: 'errors.unknown' };
}

---

HTTP статусы

MUST

• В проекте существует единый enum или константа со статусами.

Пример

export const HTTP_STATUS = {
  BadRequest: 400,
  Unauthorized: 401,
  Forbidden: 403,
  NotFound: 404,
  Conflict: 409,
  InternalServerError: 500,
  BadGateway: 502,
  ServiceUnavailable: 503
} as const;

---

Запрещённые практики

FORBIDDEN

• Передавать raw ошибки напрямую в UI.
• Показывать пользователю error.message из back-end.