# Ошибки

> Формат ошибок PS Wallet Pay API, все коды ошибок и что делать при каждой из них.

Если запрос не выполнен, API отвечает `ok: false` и описанием ошибки. По `name` удобно определять причину в коде, а `code` совпадает с HTTP-статусом ответа.

## Формат

```json
{
  "ok": false,
  "error": { "code": 400, "name": "PARAM_AMOUNT_INVALID" }
}
```

| Поле | Тип | Описание |
|---|---|---|
| `code` | Number | HTTP-статус ответа. |
| `name` | String | Машинное имя ошибки, например `INSUFFICIENT_FUNDS`. |

## Коды ошибок

| Код | Имя | Что значит |
|---|---|---|
| 400 | `PARAM_<ИМЯ>_REQUIRED` | Не передан обязательный параметр, например `PARAM_AMOUNT_REQUIRED`. |
| 400 | `PARAM_<ИМЯ>_INVALID` | Неверное значение параметра, например `PARAM_ASSET_INVALID`, `PARAM_AMOUNT_INVALID`. |
| 400 | `INSUFFICIENT_FUNDS` | На балансе приложения не хватает денег. |
| 400 | `SPEND_ID_USED` | Перевод с таким `spend_id` уже был. |
| 400 | `INVOICE_PAID` | Счёт уже оплачен (например, при `deleteInvoice`). |
| 400 | `CHECK_ALREADY_ACTIVATED` | Чек уже активирован, удалить его нельзя. |
| 401 | `UNAUTHORIZED` | Нет токена, токен неверный или перевыпущен, приложение удалено. |
| 403 | `METHOD_DISABLED` | Метод (`transfer` или `createCheck`) выключен в разделе «Безопасность». |
| 403 | `IP_NOT_ALLOWED` | Включён белый список IP, а запрос пришёл с другого адреса. |
| 403 | `APP_FROZEN` | Приложение заморожено администрацией PS Wallet. Обратитесь в поддержку. |
| 403 | `TRANSFERS_DISABLED` | Переводы для владельца приложения ограничены (`transfer` и `createCheck`). |
| 403 | `TEMPORARILY_UNAVAILABLE` | Операция в этой монете сейчас недоступна — например, перевод или чек в рублях. |
| 404 | `USER_NOT_FOUND` | Получатель не найден: он ни разу не открывал PS Wallet. |
| 404 | `INVOICE_NOT_FOUND` | Счёт не найден. |
| 404 | `CHECK_NOT_FOUND` | Чек не найден. |
| 405 | `METHOD_NOT_FOUND` | Такого метода нет. |
| 405 | `POST_REQUIRED` | Метод, который создаёт или удаляет данные, вызван через `GET`. |
| 429 | `TOO_MANY_REQUESTS` | Превышен лимит запросов, повторите позже. |
| 500 | `INTERNAL_ERROR` | Внутренняя ошибка. Повторите запрос; для `transfer` сначала проверьте `getTransfers` по `spend_id`. |
| 503 | `TEMPORARILY_UNAVAILABLE` | PS Wallet Pay временно недоступен. |

Новые коды могут добавляться. Обрабатывайте неизвестные коды как общую ошибку.

## Ошибки параметров

Имя ошибки параметра строится из имени параметра в верхнем регистре: `PARAM_` + имя + `_REQUIRED` или `_INVALID`. Например, неверный `expires_in` даст `PARAM_EXPIRES_IN_INVALID`.

| Метод | Параметры, которые проверяются |
|---|---|
| `createInvoice` | `currency_type`, `asset`, `fiat`, `accepted_assets`, `amount`, `description`, `hidden_message`, `paid_btn_name`, `paid_btn_url`, `payload`, `allow_comments`, `allow_anonymous`, `expires_in` |
| `getInvoices` | `asset`, `fiat`, `invoice_ids`, `status`, `offset`, `count` |
| `deleteInvoice` | `invoice_id` |
| `transfer` | `user_id`, `asset`, `amount`, `spend_id`, `comment` |
| `getTransfers` | `asset`, `transfer_ids`, `offset`, `count` |
| `createCheck` | `asset`, `amount`, `pin_to_user_id`, `pin_to_username` |
| `getChecks` | `asset`, `check_ids`, `status`, `offset`, `count` |
| `deleteCheck` | `check_id` |
| `getStats` | `start_at`, `end_at` |

Когда возникает каждая ошибка, описано в разделах методов: [Счета](https://help.pswallet.org/ru/pay-api/invoices), [Переводы](https://help.pswallet.org/ru/pay-api/transfers), [Чеки](https://help.pswallet.org/ru/pay-api/checks), [Приложение, баланс и курсы](https://help.pswallet.org/ru/pay-api/balance).

## Что делать при ошибке

| Ошибка | Что делать |
|---|---|
| `PARAM_…` | Исправьте параметр. Повтор с теми же данными не поможет. |
| `INSUFFICIENT_FUNDS` | Пополните баланс приложения или уменьшите сумму. |
| `401 UNAUTHORIZED` | Проверьте токен: возможно, его перевыпустили. |
| `403 IP_NOT_ALLOWED` | Добавьте адрес сервера в белый список IP или очистите список. |
| `403 METHOD_DISABLED` | Включите метод в кабинете: «Безопасность». |
| `429 TOO_MANY_REQUESTS` | Подождите и повторите запрос, увеличивая паузу между попытками. |
| `500 INTERNAL_ERROR` | Повторите запрос позже. Для `transfer` сначала проверьте `getTransfers` по `spend_id`. |
| `503 TEMPORARILY_UNAVAILABLE` | PS Wallet Pay временно не работает — повторите позже. |
| `403 APP_FROZEN`, `403 TRANSFERS_DISABLED` | Обратитесь в поддержку PS Wallet. |

> [!WARNING]
> Если запрос `transfer` оборвался по таймауту или вернул `500`, не отправляйте перевод с новым `spend_id` — сначала проверьте `getTransfers` с прежним `spend_id`. Иначе пользователь может получить деньги дважды.

---
Источник: https://help.pswallet.org/ru/pay-api/errors