# Ошибки

Ошибка — это HTTP-код не из `2xx` и тело вида:

```json
{
  "error": {
    "code": "validation_error",
    "message": "Некорректные параметры запроса",
    "details": { "issues": [{ "path": "amount", "message": "минимум 100 копеек (1 ₽)" }] }
  }
}
```

Ветвитесь по `error.code`. `message` написан для человека и может меняться.

| HTTP | `code` | Что делать |
|---|---|---|
| 400 | `invalid_json` | Тело не JSON |
| 401 | `unauthorized` | Проверьте ключ и заголовок `Authorization` |
| 403 | `merchant_disabled` | Сервис отключён, обратитесь к администратору |
| 403 | `live_payment` | Симуляция для live-платежа запрещена |
| 404 | `not_found` | Платёж не найден (или он из другого режима или сервиса) |
| 409 | `order_id_conflict` | Платёж с этим `order_id` уже есть с другой суммой |
| 409 | `order_closed` | Платёж с этим `order_id` уже завершён без оплаты, нужен новый `order_id` |
| 409 | `not_cancelable` | Отменить можно только `pending` |
| 409 | `not_refundable` | Вернуть можно только `succeeded` / `partially_refunded` |
| 409 | `not_pending` | Платёж уже не ожидает оплаты |
| 422 | `validation_error` | Ошибки полей в `details.issues` (в т.ч. не передан `customer.email` / `customer.phone`) |
| 422 | `invalid_return_url` | `return_url` должен быть `https` |
| 422 | `return_url_not_allowed` | Хост `return_url` не в `allowed_return_hosts` сервиса |
| 422 | `receipt_mismatch` | Сумма позиций чека не равна `amount` |
| 422 | `receipt_contact_required` | Для чека нужен email или телефон |
| 422 | `invalid_refund_amount` | Сумма возврата больше остатка |
| 500 | `internal_error` | Ошибка у нас. Повторите позже |
| 502 | `provider_error` | Т-Банк вернул ошибку, код в `details.provider_code`. Платёж **не** создан, можно повторить с тем же `order_id` |
| 503 | `provider_not_configured` | Боевой терминал не настроен в EGN Pay |

## Ретраи

Повторять безопасно:

- `POST /payments` с тем же `order_id`: дубля не будет;
- любые `GET`;
- `502`, `500` и сетевые таймауты, лучше с экспоненциальной задержкой.

Не повторяйте `4xx` без исправления запроса.