Какой HTTP статус код выводить при отсутствии данных в БД?

Выбор HTTP статус кода при отсутствии данных

При отсутствии данных в базе данных необходимо использовать 404 Not Found — это стандартный и правильный статус код для такой ситуации.

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

Статус код 404 означает, что запрашиваемый ресурс не найден на сервере. Это применимо в следующих случаях:

• Пользователь запрашивает конкретный ресурс по ID: GET /api/v1/users/123 — если пользователя с ID 123 нет в БД, возвращаем 404
• Запрос данных по другим уникальным параметрам: GET /api/v1/posts/slug-name — если поста с таким slug нет, это 404
• Любая операция с несуществующим ресурсом должна вернуть 404

Примеры реализации

from fastapi import FastAPI, HTTPException, status

app = FastAPI()

@app.get("/api/v1/users/{user_id}")
async def get_user(user_id: int):
    user = await db.users.get(user_id)
    if not user:
        raise HTTPException(
            status_code=status.HTTP_404_NOT_FOUND,
            detail="Пользователь не найден"
        )
    return user

Когда НЕ использовать 404

200 OK с пустым списком — если запрашиваем коллекцию (например, все посты пользователя):

@app.get("/api/v1/users/{user_id}/posts")
async def get_user_posts(user_id: int):
    # Проверяем, что пользователь существует
    user = await db.users.get(user_id)
    if not user:
        raise HTTPException(status_code=404, detail="Пользователь не найден")
    
    # Если постов нет — это OK, возвращаем пустой список
    posts = await db.posts.filter(user_id=user_id)
    return posts  # Может быть []

Другие статус коды в контексте данных

• 200 OK — данные найдены и успешно возвращены
• 204 No Content — операция выполнена, но нет контента для возврата (редко используется)
• 400 Bad Request — ошибка в параметрах запроса (неверный формат ID, невалидные фильтры)
• 401 Unauthorized — недостаточно прав доступа
• 403 Forbidden — доступ запрещён
• 404 Not Found — ресурс не существует в БД
• 500 Internal Server Error — ошибка на сервере при получении данных

Лучшие практики

Всегда проверяй наличие ресурса перед выполнением операций над ним:

@app.put("/api/v1/users/{user_id}")
async def update_user(user_id: int, data: UserUpdate):
    user = await db.users.get(user_id)
    if not user:
        raise HTTPException(status_code=404, detail="Пользователь не найден")
    
    updated = await db.users.update(user_id, data)
    return updated

@app.delete("/api/v1/users/{user_id}")
async def delete_user(user_id: int):
    user = await db.users.get(user_id)
    if not user:
        raise HTTPException(status_code=404, detail="Пользователь не найден")
    
    await db.users.delete(user_id)
    return {"status": "deleted"}

Консистентность — используй 404 для всех операций (GET, PUT, DELETE) на несуществующих ресурсах, но 200 с пустым списком для коллекций.