---
title: Разобрать ожидаемую ошибку API
description: Свяжите статус ответа с типизированным исключением и моделью проблемы.
sources:
  - eazy_sdk.api
  - eazy_sdk.response
api_fingerprint: "sha256:fe9ff583491945260b6a11e39a02e4bba57aa8b5b8add31aa2b9df8886ab7347"
---

Ожидаемый отказ входит в контракт операции. Объявите модель тела, наследника `ApiError` и
соответствие в `errors=`. Вызывающий сможет обработать каждый исход отдельным `except`, без
ветвления по числовому статусу.

| Ответ сайта | Правило операции | Что получает вызывающий |
|---|---|---|
| `200` с заказом | `HttpOperation[Order]` | `Order` |
| `404` с проблемой | `errors={404: OrderNotFound}` | `OrderNotFound` |
| `429` с проблемой | `errors={429: RateLimited}` | `RateLimited` |

:::::{grid} 1 1 2 2
:class-container: http-exchange
:gutter: 2
::::{grid-item}
:class: http-panel http-panel--request
**→ Request** · ``GET /orders/missing``
::::
::::{grid-item}
:class: http-panel http-panel--response
**← Response** · ``404 Not Found``
```json
{"code": "order_not_found", "message": "Unknown order missing"}
```
::::
:::::

```{literalinclude} ../../../../../../examples/docs/response_errors.py
:language: python
:start-after: "# docs:example:start"
:end-before: "# docs:example:end"
```

`ApiError[ApiProblem]` сохраняет типизированное тело в `.error`. Свойство `.summary` содержит
безопасную сводку: идентификатор операции, статус, тип содержимого, номер попытки, метод и
отредактированный адрес. Полный контекст ответа остаётся в `.context`.

:::{dropdown} Файл примера целиком
```{literalinclude} ../../../../../../examples/docs/response_errors.py
:language: python
```
:::

Запуск: `uv run python examples/docs/response_errors.py`.

<!-- example-output: examples.docs.response_errors -->
```text
404: Unknown order missing
429: rate_limited
```

## Разместить общие ошибки

Операция объявляет собственные ошибки. Роутер добавляет отказы всего сервиса через `errors`, а
`ClientConfig(errors=...)` задаёт ответы конкретного хоста. При совпадении выигрывает объявление,
которое находится ближе к операции.

Условие `when=` различает ответы с одинаковым статусом по телу, заголовку или типу содержимого.
Предикаты из `eazy_sdk.response.match` проверяют сырые байты до разбора модели. Неизвестный ответ
даёт `UnexpectedResponseError`, а неверное тело уже выбранного случая даёт
`MalformedResponseError`.

## Дальше

- {doc}`Настройте повторы временных ошибок </guide/reliability/retry>`.
- {doc}`Опишите варианты многошагового входа </guide/auth/login>`.
- {doc}`Проверьте полный контракт случаев ответа </reference/api/response>`.