Какую ошибку вывести, если пользователь не найден?

Обработка ошибки "Пользователь не найден": стратегии и лучшие практики

Выбор конкретной HTTP-статуса и формата сообщения об ошибке зависит от архитектуры вашего приложения, но я рекомендую комплексный подход, состоящий из нескольких слоев.

HTTP-уровень: статус 404 Not Found

На уровне HTTP/REST API наиболее семантически правильным является статус 404:

HTTP/1.1 404 Not Found
Content-Type: application/json

{
  "error": {
    "code": "USER_NOT_FOUND",
    "message": "Пользователь с указанным идентификатором не найден",
    "details": {
      "userId": "12345",
      "requestId": "req-67890"
    }
  }
}

Почему именно 404?

• Соответствует семантике HTTP: ресурс (пользователь) не существует по указанному URI
• Клиенты (браузеры, мобильные приложения) уже имеют встроенную логику обработки 404
• Альтернатива 404 — но она менее специфична для REST API

Уровень бизнес-логики: структурированные ошибки

В коде приложения создайте специализированный класс ошибки:

class UserNotFoundError extends Error {
  constructor(userId, message = 'Пользователь не найден') {
    super(message);
    this.name = 'UserNotFoundError';
    this.code = 'USER_NOT_FOUND';
    this.statusCode = 404;
    this.userId = userId;
    this.timestamp = new Date().toISOString();
  }
  
  toJSON() {
    return {
      error: {
        code: this.code,
        message: this.message,
        details: {
          userId: this.userId,
          timestamp: this.timestamp
        }
      }
    };
  }
}

// Использование в сервисе
async function getUserById(id) {
  const user = await UserRepository.findById(id);
  if (!user) {
    throw new UserNotFoundError(id, `Пользователь с ID ${id} не существует`);
  }
  return user;
}

Уровень пользовательского интерфейса

В UI важно различать технические и пользовательские сообщения:

// React-компонент обработки ошибок
function UserProfile({ userId }) {
  const { data, error, isLoading } = useUserQuery(userId);
  
  if (error?.code === 'USER_NOT_FOUND') {
    return (
      <div className="error-container">
        <h3>Пользователь не найден</h3>
        <p>Запрошенный профиль недоступен. Возможно, он был удален или вы указали неверный идентификатор.</p>
        <button onClick={() => navigate('/users')}>Вернуться к списку</button>
      </div>
    );
  }
  
  // Остальная логика компонента
}

Ключевые принципы проектирования ошибок

1. Консистентность формата — используйте единую структуру для всех ошибок API
2. Безопасность информации — не раскрывайте внутренние данные (например, "Пользователь с email test@test.com не найден")
3. Actionable сообщения — давайте пользователю возможность исправить ситуацию
4. Логирование — сохраняйте детальную информацию для разработчиков:

// Логирование с контекстом
try {
  await getUserById(userId);
} catch (error) {
  if (error instanceof UserNotFoundError) {
    // Для пользователя: простой текст
    showUserMessage('Пользователь не найден');
    
    // Для разработчика: полный контекст
    logger.warn('UserNotFoundError', {
      error: error.toJSON(),
      userId: error.userId,
      stack: error.stack,
      userAgent: navigator.userAgent
    });
  }
}

Дополнительные соображения

• Международная локализация — подготовьте переводы сообщений об ошибках
• Временная недоступность — если пользователь может появиться позже, рассмотрите статус 410 Gone
• GraphQL альтернатива — в GraphQL используйте кастомные типы ошибок:

type UserNotFoundError implements Error {
  message: String!
  code: String!
  userId: ID!
  suggestedUsers: [User!]
}

Выбор конкретной реализации зависит от требований вашего проекта, но сочетание HTTP 404 со структурированным JSON-ответом и специализированными классами ошибок в коде обеспечивает максимальную гибкость и поддерживаемость решения.