# Обробка Помилок

Є багато ситуацій, коли потрібно повідомити клієнта, який використовує Ваш API, про помилку.

Цим клієнтом може бути браузер із фронтендом, код іншого розробника, IoT-пристрій тощо.

Можливо, Вам потрібно повідомити клієнта, що:

* У нього недостатньо прав для виконання цієї операції.
* Він не має доступу до цього ресурсу.
* Елемент, до якого він намагається отримати доступ, не існує.
* тощо.

У таких випадках зазвичай повертається **HTTP статус-код** в діапазоні **400** (від 400 до 499).

Це схоже на HTTP статус-коди 200 (від 200 до 299). Ці "200" статус-коди означають, що запит пройшов успішно.

Статус-коди в діапазоні 400 означають, що сталася помилка з боку клієнта.

Пам'ятаєте всі ці помилки **404 Not Found** (і жарти про них)?

## Використання `HTTPException`

Щоб повернути HTTP-відповіді з помилками клієнту, використовуйте `HTTPException`.

### Імпорт `HTTPException`

{* ../../docs_src/handling_errors/tutorial001.py hl[1] *}

### Використання `HTTPException` у коді

`HTTPException` — це звичайна помилка Python із додатковими даними, які стосуються API.

Оскільки це помилка Python, Ви не `повертаєте` його, а `генеруєте` (генеруєте помилку).

Це також означає, що якщо Ви перебуваєте всередині допоміжної функції, яку викликаєте всередині своєї *функції операції шляху*, і там генеруєте `HTTPException`, всередині цієї допоміжної функції, то решта коду в *функції операції шляху* не буде виконана. Запит одразу завершиться, і HTTP-помилка з `HTTPException` буде надіслана клієнту.

Перевага використання `генерації` (raise) помилки замість `повернення` значення (return) стане більш очевидним в розділі про Залежності та Безпеку.

У цьому прикладі, якщо клієнт запитує елемент за ID, якого не існує, буде згенеровано помилку зі статус-кодом `404`:

{* ../../docs_src/handling_errors/tutorial001.py hl[11] *}

### Отримана відповідь

Якщо клієнт робить запит за шляхом `http://example.com/items/foo` (де `item_id` `"foo"`), він отримає статус-код 200 і JSON відповідь:

```JSON
{
  "item": "The Foo Wrestlers"
}
```

Але якщо клієнт робить запит на `http://example.com/items/bar` (де `item_id` має не існуюче значення `"bar"`), то отримає статус-код 404 (помилка "не знайдено") та відповідь:

```JSON
{
  "detail": "Item not found"
}
```

/// tip | Порада

Під час виклику `HTTPException` Ви можете передати будь-яке значення, яке може бути перетворене в JSON, як параметр `detail`, а не лише рядок (`str`).

Ви можете передати `dict`, `list` тощо.

Вони обробляються автоматично за допомогою **FastAPI** та перетворюються в JSON.

///

## Додавання власних заголовків

Іноді потрібно додати власні заголовки до HTTP-помилки, наприклад, для певних типів безпеки.

Ймовірно, Вам не доведеться використовувати це безпосередньо у своєму коді.

Але якщо Вам знадобиться це для складного сценарію, Ви можете додати власні заголовки:

{* ../../docs_src/handling_errors/tutorial002.py hl[14] *}

## Встановлення власних обробників помилок

Ви можете додати власні обробники помилок за допомогою <a href="https://www.starlette.dev/exceptions/" class="external-link" target="_blank">тих самих утиліт обробки помилок зі Starlette</a>.

Припустимо, у Вас є власний обʼєкт помилки `UnicornException`, яке Ви (або бібліотека, яку Ви використовуєте) може `згенерувати` (`raise`).

І Ви хочете обробляти це виключення глобально за допомогою FastAPI.

Ви можете додати власний обробник виключень за допомогою `@app.exception_handler()`:

{* ../../docs_src/handling_errors/tutorial003.py hl[5:7,13:18,24] *}

Тут, якщо Ви звернетеся до `/unicorns/yolo`, то згенерується помилка `UnicornException`.

Але вона буде оброблена функцією-обробником `unicorn_exception_handler`.

Отже, Ви отримаєте зрозумілу помилку зі HTTP-статусом `418` і JSON-відповіддю:

```JSON
{"message": "Oops! yolo did something. There goes a rainbow..."}
```

/// note | Технічні деталі

Ви також можете використовувати `from starlette.requests import Request` і `from starlette.responses import JSONResponse`.

**FastAPI** надає ті самі `starlette.responses`, що й `fastapi.responses`, просто для зручності розробника. Але більшість доступних відповідей надходять безпосередньо зі Starlette. Те ж саме стосується і `Request`.

///

## Перевизначення обробників помилок за замовчуванням

**FastAPI** має кілька обробників помилок за замовчуванням.

Ці обробники відповідають за повернення стандартних JSON-відповідей, коли Ви `генеруєте` (`raise`) `HTTPException`, а також коли запит містить некоректні дані.

Ви можете перевизначити ці обробники, створивши власні.

### Перевизначення помилок валідації запиту

Коли запит містить некоректні дані, **FastAPI** генерує `RequestValidationError`.

І також включає обробник помилок за замовчуванням для нього.

Щоб перевизначити його, імпортуйте `RequestValidationError` і використовуйте його з `@app.exception_handler(RequestValidationError)` для декорування обробника помилок.

Обробник помилок отримує `Request` і саму помилку.

{* ../../docs_src/handling_errors/tutorial004.py hl[2,14:16] *}

Тепер, якщо Ви перейдете за посиланням `/items/foo`, замість того, щоб отримати стандартну JSON-помилку:

```JSON
{
    "detail": [
        {
            "loc": [
                "path",
                "item_id"
            ],
            "msg": "value is not a valid integer",
            "type": "type_error.integer"
        }
    ]
}
```

Ви отримаєте текстову версію:

```
1 validation error
path -> item_id
  value is not a valid integer (type=type_error.integer)
```

#### `RequestValidationError` проти `ValidationError`

/// warning | Увага

Це технічні деталі, які Ви можете пропустити, якщо вони зараз не важливі для Вас.

///

`RequestValidationError` є підкласом Pydantic <a href="https://docs.pydantic.dev/latest/concepts/models/#error-handling" class="external-link" target="_blank">`ValidationError`</a>.

**FastAPI** використовує його для того, якщо Ви використовуєте модель Pydantic у `response_model` і у ваших даних є помилка, Ви побачили помилку у своєму журналі.

Але клієнт/користувач не побачить її. Натомість клієнт отримає "Internal Server Error" зі статусом HTTP `500`.

Так має бути, якщо у Вас виникла `ValidationError` Pydantic у *відповіді* або деінде у вашому коді (не у *запиті* клієнта), це насправді є помилкою у Вашому коді.

І поки Ви її виправляєте, клієнти/користувачі не повинні мати доступу до внутрішньої інформації про помилку, оскільки це може призвести до вразливості безпеки.

### Перевизначення обробника помилок `HTTPException`

Аналогічно, Ви можете перевизначити обробник `HTTPException`.

Наприклад, Ви можете захотіти повернути текстову відповідь замість JSON для цих помилок:

{* ../../docs_src/handling_errors/tutorial004.py hl[3:4,9:11,22] *}

/// note | Технічні деталі

Ви також можете використовувати `from starlette.responses import PlainTextResponse`.

**FastAPI** надає ті самі `starlette.responses`, що й `fastapi.responses`, просто для зручності розробника. Але більшість доступних відповідей надходять безпосередньо зі Starlette.

///

### Використання тіла `RequestValidationError`

`RequestValidationError` містить `body`, який він отримав із некоректними даними.

Ви можете використовувати це під час розробки свого додатка, щоб логувати тіло запиту та налагоджувати його, повертати користувачеві тощо.

{* ../../docs_src/handling_errors/tutorial005.py hl[14] *}

Тепер спробуйте надіслати некоректний елемент, наприклад:

```JSON
{
  "title": "towel",
  "size": "XL"
}
```
Ви отримаєте відповідь, яка повідомить Вам, які саме дані є некоректні у вашому тілі запиту:


```JSON hl_lines="12-15"
{
  "detail": [
    {
      "loc": [
        "body",
        "size"
      ],
      "msg": "value is not a valid integer",
      "type": "type_error.integer"
    }
  ],
  "body": {
    "title": "towel",
    "size": "XL"
  }
}
```

#### `HTTPException` FastAPI проти `HTTPException` Starlette

**FastAPI** має власний `HTTPException`.

І клас помилки `HTTPException` в **FastAPI** успадковується від класу помилки `HTTPException` в Starlette.

Єдина різниця полягає в тому, що `HTTPException` в **FastAPI** приймає будь-які дані, які можна перетворити на JSON, для поля `detail`, тоді як `HTTPException` у Starlette приймає тільки рядки.

Отже, Ви можете продовжувати використовувати `HTTPException` в **FastAPI** як зазвичай у своєму коді.

Але коли Ви реєструєте обробник виключень, слід реєструвати його для `HTTPException` зі Starlette.

Таким чином, якщо будь-яка частина внутрішнього коду Starlette або розширення чи плагін Starlette згенерує (raise) `HTTPException`, Ваш обробник зможе перехопити та обробити її.

У цьому прикладі, щоб мати можливість використовувати обидва `HTTPException` в одному коді, помилка Starlette перейменовується на `StarletteHTTPException`:

```Python
from starlette.exceptions import HTTPException as StarletteHTTPException
```

### Повторне використання обробників помилок **FastAPI**

Якщо Ви хочете використовувати помилки разом із такими ж обробниками помилок за замовчуванням, як у **FastAPI**, Ви можете імпортувати та повторно використовувати їх із `fastapi.exception_handlers`:

{* ../../docs_src/handling_errors/tutorial006.py hl[2:5,15,21] *}

У цьому прикладі Ви просто використовуєте `print` для виведення дуже інформативного повідомлення, але Ви зрозуміли основну ідею. Ви можете обробити помилку та повторно використовувати обробники помилок за замовчуванням.
