# Ошибки

HTTP API Platform, Management и VKS используют Problem Details (`application/problem+json`). Проверяйте статус и машинный `code` с учётом вызванной операции. Коды - открытые строки, а не исчерпывающий enum; предусмотрите обработку неизвестных значений. Человекочитаемые `title` и `detail` не подходят для ветвления.

Problem Details · problem+json
Проверяйте `code`
Поля зависят от схемы
RPC: ошибки протокола

## Тело ошибки 

| Поле | Обязательно | Значение |
|  --- | --- | --- |
| `type` | да | URI категории проблемы |
| `title` | да | Человекочитаемое название |
| `status` | да | HTTP-статус |
| `code` | да | Машинный код сервиса; иногда `unspecified` |
| `detail` | нет | Пояснение для этого случая |
| `instance` | нет | Идентификатор случая; приложите его к обращению в поддержку |


```json
{
  "type": "https://docs.vilna.io/apis/errors#not-found",
  "title": "Not Found",
  "status": 404,
  "code": "address.not_found",
  "detail": "address not found",
  "instance": "/traces/0123456789abcdef0123456789abcdef"
}
```

Для полей `fields`, `max` или `window_seconds` используйте схему, указанную в операции.

## Коды статуса 

400

Invalid Request

Исправьте некорректный запрос. Platform и Management могут использовать разные коды при одном статусе.

```json
{
  "type": "https://docs.vilna.io/apis/errors#invalid-request",
  "title": "Invalid Request",
  "status": 400,
  "code": "request.malformed",
  "detail": "The request could not be decoded.",
  "instance": "/traces/0123456789abcdef0123456789abcdef"
}
```

401

Unauthorized

Проверьте учётные данные и их назначение.

```json
{
  "type": "https://docs.vilna.io/apis/errors#unauthorized",
  "title": "Unauthorized",
  "status": 401,
  "code": "unspecified",
  "detail": "You are not authorized to access this resource. If the problem persists, please contact our support team.",
  "instance": "/unauthorized?method=createInvoice"
}
```

403

Forbidden

Недостаточно доступа. Проверьте текущие права; ключ идемпотентности не даёт доступа.

404

Not Found

Ресурс отсутствует или недоступен вызывающему.

```json
{
  "type": "https://docs.vilna.io/apis/errors#not-found",
  "title": "Not Found",
  "status": 404,
  "code": "project.not_found",
  "detail": "project not found",
  "instance": "/traces/0199ce911a2b7c019c2a9d0010eaa310"
}
```

405

Method Not Allowed

Используйте метод, поддерживаемый маршрутом.

408

Request Canceled

Отмена соединения не доказывает, что изменение не произошло. Повторяйте с исходным ключом идемпотентности и параметрами, если операция требует ключ.

409

Conflict

Операция конфликтует с состоянием ресурса или связью идемпотентности. Перед дальнейшими действиями проверьте `code`.

```json
{
  "type": "https://docs.vilna.io/apis/errors#conflict",
  "title": "Conflict",
  "status": 409,
  "code": "invoice.address_occupied",
  "detail": "address already has an active invoice with different parameters",
  "instance": "/traces/0123456789abcdef0123456789abcdef"
}
```

413

Request Too Large

Уменьшите тело до допустимого размера.

422

Precondition Failed

Запрос отклонён бизнес-правилом или условием состояния. Устраните причину перед повтором.

```json
{
  "type": "https://docs.vilna.io/apis/errors#precondition",
  "title": "Precondition Failed",
  "status": 422,
  "code": "invoice.not_cancellable",
  "detail": "invoice cannot be cancelled in current status",
  "instance": "/traces/0123456789abcdef0123456789abcdef",
  "fields": [
    {
      "name": "status",
      "reason": "confirmed"
    }
  ]
}
```

429

Too Many Requests

Это может быть квота ресурсов, окно действий или пауза перед повторной отправкой. Разные способы восстановления описаны в разделе [Лимиты](#rate-limits).

501

Not Implemented

Операция не поддерживается. Повтор запроса не добавит поддержку.

502

Bad Gateway

Нужный сервис недоступен. Повторяйте исходный запрос с задержкой, сохраняя ключ идемпотентности и параметры.

503

Service Unavailable

Операция временно недоступна. Повторяйте с задержкой, сохраняя ключ изменения и параметры.

```json
{
  "type": "https://docs.vilna.io/apis/errors#service-unavailable",
  "title": "Service Unavailable",
  "status": 503,
  "code": "service.temporarily_unavailable",
  "detail": "The operation is temporarily unavailable. Please try again later."
}
```

504

Gateway Timeout

Истёк срок ожидания запроса. Результат может быть неизвестен; при повторе используйте исходный ключ идемпотентности и параметры запроса.

5xx

Server Error

Неожиданная ошибка сервера не доказывает отсутствие эффекта. Используйте задержку и исходный ключ изменения; если ответ недоступен, сверьте состояние.

### Конфликты идемпотентности 

Конфликты `idempotency_in_progress`, `idempotency_request_mismatch`, `idempotency_result_expired` и `idempotency_result_unavailable` требуют разных действий. Сохраняйте исходный ключ и данные запроса; не подставляйте новый ключ автоматически при неизвестном исходе. Область действия, сроки и действия для каждого API описаны в [Идемпотентности](/ru/apis/idempotency#recovery). Некорректный или повторный заголовок приводит к `400`, а не к конфликту `409`.

## Поля валидации 

Схемы `400` и `422` могут содержать `fields`, массив объектов `{ "name": "…", "reason": "…" }`. Элементы могут описывать некорректный ввод или диагностическое состояние, например `name: status`, `reason: confirmed`, когда счёт нельзя отменить. При некорректном JSON конкретное поле может быть не указано.

## Лимиты и квоты 

### Количество ресурсов

`QuotaExceededProblem` добавляет `max`, действующий предел ресурсов в области операции. Это не текущее использование и не остаток. Ожидание не освобождает ёмкость: уменьшите использование, если продукт это позволяет, или измените лимит. Нулевой предел запрещает новые ресурсы, не отключая уже существующие.

```json
{
  "type": "https://docs.vilna.io/apis/errors#too-many-requests",
  "title": "Too Many Requests",
  "status": 429,
  "code": "address.quota_exceeded",
  "detail": "the project has reached its address limit",
  "max": 100
}
```

```json
{
  "type": "https://docs.vilna.io/apis/errors#too-many-requests",
  "title": "Too Many Requests",
  "status": 429,
  "code": "project.limit_exceeded",
  "detail": "project limit exceeded",
  "max": 2
}
```

### Временные окна

Для обновления баланса `RateLimitExceededProblem` добавляет `max` и `window_seconds`. Продолжительность окна не равна оставшемуся ожиданию. `Retry-After` указывает целые секунды до ближайшего повтора, когда `max > 0` и срок известен; при `max: 0` или неизвестном сроке заголовок отсутствует. При нулевом лимите нужна смена политики, а не только ожидание. Следующая попытка снова проверяет ёмкость.

```json
{
  "type": "https://docs.vilna.io/apis/errors#too-many-requests",
  "title": "Too Many Requests",
  "status": 429,
  "code": "balance.refresh_rate_exceeded",
  "detail": "the project has reached its balance refresh rate limit",
  "max": 1,
  "window_seconds": 60
}
```

### Пауза перед ручной повторной отправкой

Повторная отправка уведомления может вернуть `429` с `notification.resend_delayed`. Её `Retry-After` - округлённое вверх ожидание до более позднего из двух сроков: паузы доставки и интервала после последней попытки. Это подсказка, а не резервирование. После ожидания повторите тот же запрос с тем же ключом идемпотентности. Запланированная или выполняющаяся отправка даёт `409 notification.send_in_progress`, утраченное содержимое - `409 notification.payload_unavailable`. Перед новым действием проверьте уведомление и его логи.

```json
{
  "type": "https://docs.vilna.io/apis/errors#too-many-requests",
  "title": "Too Many Requests",
  "status": 429,
  "code": "notification.resend_delayed",
  "detail": "notification resend is delayed",
  "instance": "/traces/0123456789abcdef0123456789abcdef"
}
```

## Типы проблем VKS 

Эти фрагменты type используются в примерах ответов публичного VKS. Это примеры открытых кодов, а не полный список возможных ответов. При записи ошибки сохраняйте переданный URI `type`.

### `backend.failure` 

Неожиданная ошибка; повторите исходный запрос с тем же ключом идемпотентности и задержкой, затем при неизвестном результате сверьте состояние.

```json
{
  "type": "https://docs.vilna.io/apis/errors#backend.failure",
  "title": "Internal Server Error",
  "status": 500,
  "code": "backend.failure",
  "detail": "internal error"
}
```

### `request.invalid` 

Исправьте запрос по схеме операции.

```json
{
  "type": "https://docs.vilna.io/apis/errors#request.invalid",
  "title": "Bad Request",
  "status": 400,
  "code": "request.invalid",
  "detail": "invalid request"
}
```

### `transaction.not_found` 

Проверьте идентификатор транзакции и доступ к рабочему пространству.

```json
{
  "type": "https://docs.vilna.io/apis/errors#transaction.not_found",
  "title": "Not Found",
  "status": 404,
  "code": "transaction.not_found",
  "detail": "transaction not found"
}
```

### `account.state_invalid` 

Проверьте состояние блокчейн-аккаунта VKS (`account`) и допустимые состояния в описании операции. Ожидание имеет смысл, пока настройка продолжается; некоторые операции недоступны и для активного аккаунта.

```json
{
  "type": "https://docs.vilna.io/apis/errors#account.state_invalid",
  "title": "Conflict",
  "status": 409,
  "code": "account.state_invalid",
  "detail": "account state does not allow this operation"
}
```

### `transaction.state_invalid` 

Прочитайте состояние транзакции перед выбором следующего действия.

```json
{
  "type": "https://docs.vilna.io/apis/errors#transaction.state_invalid",
  "title": "Conflict",
  "status": 409,
  "code": "transaction.state_invalid",
  "detail": "transaction state does not allow this operation"
}
```

### `transaction.send_in_progress` 

Отправка уже ожидается. Проверьте историю, не ставьте новую отправку.

```json
{
  "type": "https://docs.vilna.io/apis/errors#transaction.send_in_progress",
  "title": "Conflict",
  "status": 409,
  "code": "transaction.send_in_progress",
  "detail": "transaction has a pending send attempt"
}
```

### `transaction.already_sent` 

Узел уже принял транзакцию. Проверьте историю отправки; это не доказывает подтверждение в блокчейне.

```json
{
  "type": "https://docs.vilna.io/apis/errors#transaction.already_sent",
  "title": "Conflict",
  "status": 409,
  "code": "transaction.already_sent",
  "detail": "transaction was already accepted by RPC"
}
```

### `transaction.send_limit_exceeded` 

`max` - общий предел ручных и автоматических попыток транзакции. Ожидание само по себе его не сбрасывает.

```json
{
  "type": "https://docs.vilna.io/apis/errors#transaction.send_limit_exceeded",
  "title": "Too Many Requests",
  "status": 429,
  "code": "transaction.send_limit_exceeded",
  "detail": "transaction send limit exceeded",
  "max": 10
}
```

### `signer.limit_exceeded` 

`max` - предел зарегистрированных узлов подписи (signer) и непросроченных приглашений рабочего пространства. Отключённые узлы подписи тоже учитываются. Удалите ненужные приглашения или узлы, для которых удаление допустимо, либо обратитесь на [support@vilna.io](mailto:support@vilna.io) по поводу лимита.

```json
{
  "type": "https://docs.vilna.io/apis/errors#signer.limit_exceeded",
  "title": "Too Many Requests",
  "status": 429,
  "code": "signer.limit_exceeded",
  "detail": "workspace signer limit exceeded",
  "max": 10
}
```

### `transaction.send_unsupported` 

Результат не является готовой к отправке транзакцией; ingredient нельзя отправить этим действием.

```json
{
  "type": "https://docs.vilna.io/apis/errors#transaction.send_unsupported",
  "title": "Unprocessable Entity",
  "status": 422,
  "code": "transaction.send_unsupported",
  "detail": "signed result is not a broadcastable transaction"
}
```

### `transaction.rpc_not_configured` 

VKS не может отправлять транзакции в эту сеть: для неё не настроен узел. Перед повтором уточните доступность сети через [support@vilna.io](mailto:support@vilna.io).

```json
{
  "type": "https://docs.vilna.io/apis/errors#transaction.rpc_not_configured",
  "title": "Unprocessable Entity",
  "status": 422,
  "code": "transaction.rpc_not_configured",
  "detail": "RPC is not configured for this network"
}
```

## Ошибки разных сервисов 

Platform, Management и VKS используют описанное выше HTTP-тело проблемы, с собственными кодами и расширениями. Blockchain RPC использует ошибки своего протокола; см. [обработку ошибок JSON-RPC](/ru/apis/rpc/json-rpc#error-handling).

### Blockchain RPC

При ограничении JSON-RPC возвращает следующую ошибку протокола, а gRPC - HTTP `429` с пустым телом.

```json
{
  "jsonrpc": "2.0",
  "error": {
    "code": -32005,
    "message": "rate limit exceeded",
    "data": {
      "source": "vilna"
    }
  },
  "id": null
}
```

Заголовки `X-RateLimit-*` не передаются. Учитывайте правила `Retry-After` конкретного ответа; не считайте каждый `429` временным окном. При допускающих повтор сетевых и серверных сбоях увеличивайте задержку и сохраняйте ключ идемпотентности и параметры исходного действия.