# Ошибки

Формат ошибок, коды ответов и что с ними делать.

Все ответы — JSON. Успешные содержат `"status": "success"`, ошибки — `"status": "error"` и `message`; у части ошибок есть машинный `code`.

```json
{
  "status": "error",
  "code": "idempotency_key_reused",
  "message": "This idempotencyKey was already used for a different product"
}
```

## Коды ответов

| Код | Когда | Что делать |
|---|---|---|
| 400 | Некорректный ID, тело или параметр. | Исправить запрос. |
| 401 / 403 | Нет ключа, неверный ключ, доступ отключён, покупки отключены. | См. «Аутентификация». |
| 402 | Недостаточно средств. Заказ не создан. | Пополнить баланс, повторить с тем же ключом. |
| 404 | Товар или заказ не найден. | Проверить ID. |
| 409 | Товар недоступен для покупки. | Обновить каталог, проверить наличие. |
| 413 / 415 | Тело больше 10 КБ или не JSON. | Исправить запрос. |
| 422 | idempotencyKey использован для другого товара. | Новый ключ для новой покупки. |
| 429 | Превышен лимит запросов. | Подождать и повторить реже. |
| 500 | Внутренняя ошибка или `key_unavailable`. | Повторить с тем же idempotencyKey / запросить заказ позже. |
| 502 | Поставщик не выполнил заказ (`failed`). Деньги возвращены. | Можно купить снова с новым ключом. |
| 503 | Временная недоступность или техработы (`maintenance_mode`). | Повторить позже. |

## Причины отказа (failureReason)

Приходят в `message` ответа покупки и в поле `failureReason` заказа со статусом `failed` или `cancelled`.

| failureReason | Значение |
|---|---|
| `insufficient_balance` | Недостаточно средств. |
| `purchase_disabled` | Покупки для клиента отключены. |
| `product_unavailable` | Товар нельзя продать сейчас: нет в наличии или цена у поставщика вышла за допустимую. |
| `fulfillment_failed` | Поставщик не выполнил заказ. |
| `fulfillment_cancelled` | Поставщик отменил или вернул заказ. |
| `client_not_found` | Клиент не найден. |

Список может пополняться: неизвестное значение обрабатывайте как общий отказ.