# Errors

> The PS Wallet Pay API error format, all error codes, and what to do for each one.

If a request fails, the API responds with `ok: false` and an error description. Use `name` to determine the cause in your code; `code` matches the HTTP status of the response.

## Format

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

| Field | Type | Description |
|---|---|---|
| `code` | Number | HTTP status of the response. |
| `name` | String | Machine-readable error name, for example `INSUFFICIENT_FUNDS`. |

## Error codes

| Code | Name | Meaning |
|---|---|---|
| 400 | `PARAM_<NAME>_REQUIRED` | A required parameter is missing, for example `PARAM_AMOUNT_REQUIRED`. |
| 400 | `PARAM_<NAME>_INVALID` | Invalid parameter value, for example `PARAM_ASSET_INVALID`, `PARAM_AMOUNT_INVALID`. |
| 400 | `INSUFFICIENT_FUNDS` | The app balance does not have enough funds. |
| 400 | `SPEND_ID_USED` | A transfer with this `spend_id` has already been made. |
| 400 | `INVOICE_PAID` | The invoice is already paid (for example, with `deleteInvoice`). |
| 400 | `CHECK_ALREADY_ACTIVATED` | The check is already activated and cannot be deleted. |
| 401 | `UNAUTHORIZED` | The token is missing, invalid, or has been reissued, or the app has been deleted. |
| 403 | `METHOD_DISABLED` | The method (`transfer` or `createCheck`) is disabled in the "Security" section. |
| 403 | `IP_NOT_ALLOWED` | The IP allowlist is enabled and the request came from a different address. |
| 403 | `APP_FROZEN` | The app has been frozen by PS Wallet administration. Contact support. |
| 403 | `TRANSFERS_DISABLED` | Transfers are restricted for the app owner (`transfer` and `createCheck`). |
| 403 | `TEMPORARILY_UNAVAILABLE` | The operation in this coin is currently unavailable — for example, a transfer or check in rubles. |
| 404 | `USER_NOT_FOUND` | The recipient was not found: they have never opened PS Wallet. |
| 404 | `INVOICE_NOT_FOUND` | The invoice was not found. |
| 404 | `CHECK_NOT_FOUND` | The check was not found. |
| 405 | `METHOD_NOT_FOUND` | No such method exists. |
| 405 | `POST_REQUIRED` | A method that creates or deletes data was called via `GET`. |
| 429 | `TOO_MANY_REQUESTS` | The request limit has been exceeded, try again later. |
| 500 | `INTERNAL_ERROR` | Internal error. Retry the request; for `transfer`, first check `getTransfers` by `spend_id`. |
| 503 | `TEMPORARILY_UNAVAILABLE` | PS Wallet Pay is temporarily unavailable. |

New codes may be added. Handle unknown codes as a generic error.

## Parameter errors

A parameter error name is built from the parameter name in uppercase: `PARAM_` + name + `_REQUIRED` or `_INVALID`. For example, an invalid `expires_in` produces `PARAM_EXPIRES_IN_INVALID`.

| Method | Parameters that are validated |
|---|---|
| `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` |

When each error occurs is described in the method sections: [Invoices](https://help.pswallet.org/en/pay-api/invoices), [Transfers](https://help.pswallet.org/en/pay-api/transfers), [Checks](https://help.pswallet.org/en/pay-api/checks), [App, balance, and rates](https://help.pswallet.org/en/pay-api/balance).

## What to do when an error occurs

| Error | What to do |
|---|---|
| `PARAM_…` | Fix the parameter. Retrying with the same data will not help. |
| `INSUFFICIENT_FUNDS` | Top up the app balance or reduce the amount. |
| `401 UNAUTHORIZED` | Check the token: it may have been reissued. |
| `403 IP_NOT_ALLOWED` | Add the server address to the IP allowlist or clear the list. |
| `403 METHOD_DISABLED` | Enable the method in the dashboard: "Security". |
| `429 TOO_MANY_REQUESTS` | Wait and retry the request, increasing the pause between attempts. |
| `500 INTERNAL_ERROR` | Retry the request later. For `transfer`, first check `getTransfers` by `spend_id`. |
| `503 TEMPORARILY_UNAVAILABLE` | PS Wallet Pay is temporarily down — try again later. |
| `403 APP_FROZEN`, `403 TRANSFERS_DISABLED` | Contact PS Wallet support. |

> [!WARNING]
> If a `transfer` request timed out or returned `500`, do not send the transfer with a new `spend_id` — first check `getTransfers` with the original `spend_id`. Otherwise, the user may receive the money twice.

---
Source: https://help.pswallet.org/en/pay-api/errors