Как корректно сообщить клиенту API, что запрошенный ресурс не найден, и какой статус-код для этого принято использовать?

Короткий ответ

Для отсутствующего ресурса возвращают HTTP-статус 404 Not Found, как правило, с JSON-телом, содержащим понятное сообщение об ошибке — конкретный формат тела зависит от принятого в проекте стандарта.

Как это работает подробнее

404 — стандартный HTTP-статус, означающий, что сервер не нашёл ресурс по данному URL/идентификатору. Клиентские библиотеки и мониторинг обычно отличают 4xx (ошибка клиента/запроса) от 5xx (ошибка сервера), поэтому важно не возвращать 500 там, где ресурс просто отсутствует.

Пример кода

example.pyКопировать

from fastapi import FastAPI, HTTPException
app = FastAPI()
items_db = {1: {"name": "Pen"}}
@app.get("/items/{item_id}")
def get_item(item_id: int):
    if item_id not in items_db:
        raise HTTPException(status_code=404, detail="Item not found")
    return items_db[item_id]
# GET /items/999 -> 404 {"detail": "Item not found"}

Что использовать на практике

• Практика. В разных фреймворках это делается по-разному: во Flask — abort(404) или возврат кортежа (body, 404); в Django — get_object_or_404(); в FastAPI — raise HTTPException(status_code=404, detail=...). Единообразный формат тела ошибки по всему API облегчает работу клиентов.

Подводные камни

• Риск. Возвращают 200 с телом вида {"error": "not found"} — клиент обязан дополнительно парсить тело, чтобы понять, что произошла ошибка, что увеличивает число пропущенных на клиенте ошибок; возвращают 500 вместо 404, когда причина — отсутствие записи, а не сбой сервера.