Какой HTTP статус-код возвращать, если ресурс не найден в базе данных?

Ответ

При отсутствии конкретного запрашиваемого ресурса в базе данных наиболее подходящим HTTP статус-кодом является 404 Not Found. Этот код указывает, что сервер не может найти ресурс по указанному URL.

Почему 404 Not Found?

Семантика: Четко сообщает клиенту, что ресурс по указанному URL не существует.
Стандарт: Общепринятый стандарт для таких ситуаций, что упрощает обработку ошибок на стороне клиента.

Пример (FastAPI):

from fastapi import FastAPI, HTTPException
from typing import Optional

app = FastAPI()

# Предположим, у нас есть функция для получения элемента из БД
def get_item_from_db(item_id: int) -> Optional[dict]:
    # Имитация обращения к БД
    if item_id == 1:
        return {"id": 1, "name": "Test Item"}
    return None

@app.get("/items/{item_id}")
async def read_item(item_id: int):
    item = get_item_from_db(item_id)
    if item is None:
        # Если ресурс не найден, выбрасываем HTTPException с 404 статусом
        raise HTTPException(status_code=404, detail=f"Item with id {item_id} not found")
    return item

Альтернативные сценарии и коды:

200 OK с пустым списком/массивом: Если запрос предполагает возврат коллекции (например, /users), и коллекция пуста, следует вернуть 200 OK с пустым JSON-массивом ([]). Это означает, что запрос успешно обработан, но данных нет.
204 No Content: Используется, когда запрос успешно обработан, но сервер не возвращает никакого содержимого (например, после успешного удаления ресурса).
400 Bad Request: Если запрос некорректен (например, неверный формат ID), а не ресурс отсутствует.