Справочник кодов ошибок

Каждая ошибка API Pert возвращается в едином JSON-формате:

{
  "error": "Описание ошибки для пользователя",
  "code": "MACHINE_READABLE_CODE",
  "details": {
    "field": "name",
    "reason": "required"
  }
}

error — человекочитаемое сообщение.
code — стабильный машиночитаемый код. Имеет смысл использовать его для условной логики обработки ошибки в клиенте.
details (опционально) — структурированные данные о причине ошибки (например, field и reason для валидационных ошибок).

HTTP-статус выводится из поля Kind ошибки:

Kind	HTTP
`validation`	400 Bad Request
`malformed`	400 Bad Request
`unauthorized`	401 Unauthorized
`forbidden`	403 Forbidden
`not_found`	404 Not Found
`conflict`	409 Conflict
`unavailable`	503 Service Unavailable
`internal`	500 Internal Server Error

Общие

`FORBIDDEN`

Клиенту запрещён доступ к ресурсу.

HTTP: 403 Forbidden
Kind: forbidden

Подробности

Клиент аутентифицирован, но у него нет нужных прав для операции. Не выдаётся при отсутствии ресурса — для этого используется *_NOT_FOUND.

`INTERNAL_ERROR`

Внутренняя ошибка сервиса.

HTTP: 500 Internal Server Error
Kind: internal

Подробности

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

`MALFORMED_JSON`

Некорректное тело запроса (не парсится как JSON).

HTTP: 400 Bad Request
Kind: malformed

Подробности

Тело запроса невалидное (битый JSON, неверная структура).

`UNAUTHORIZED`

Клиент не аутентифицирован.

HTTP: 401 Unauthorized
Kind: unauthorized

Подробности

Отсутствует или невалиден bearer-токен / сессионная кука. Клиенту нужно повторить аутентификацию.

`VALIDATION_ERROR`

Ошибка валидации входных данных.

HTTP: 400 Bad Request
Kind: validation

Подробности

Значение хотя бы одного поля запроса не соответствует требованиям. Дополнительные данные (имя поля, причина) приходят в Details.

Workspace

`WORKSPACE_ALREADY_ASSOCIATED`

Workspace уже связан с MPC-конфигурацией.

HTTP: 409 Conflict
Kind: conflict

Подробности

Попытка повторно ассоциировать workspace с конфигами после того, как ассоциация уже произведена.

`WORKSPACE_ALREADY_EXISTS`

Конфликт уникальности при создании workspace.

HTTP: 409 Conflict
Kind: conflict

Подробности

Workspace с таким же уникальным набором атрибутов уже существует.

`WORKSPACE_NOT_FOUND`

Workspace не найден.

HTTP: 404 Not Found
Kind: not_found

Подробности

Запрошенный workspace отсутствует в БД или недоступен текущему пользователю.

`WORKSPACE_STATUS_INCOMPATIBLE`

Статус workspace не позволяет операцию.

HTTP: 409 Conflict
Kind: conflict

Подробности

Операция требует определённого статуса workspace (например, активации нужен статус new), но текущий статус другой.

Vault

`VAULT_ALREADY_EXISTS`

Vault с таким именем уже существует в workspace.

HTTP: 409 Conflict
Kind: conflict

Подробности

Имя vault должно быть уникальным в рамках workspace.

`VAULT_FROZEN`

Операция недопустима над замороженным vault.

HTTP: 409 Conflict
Kind: conflict

Подробности

Vault находится в статусе frozen — действие требует предварительной разморозки.

`VAULT_NOT_FOUND`

Vault не найден.

HTTP: 404 Not Found
Kind: not_found

Подробности

Запрошенный vault отсутствует, удалён или принадлежит другому workspace.

`VAULT_UNFREEZE_BLOCKED_BY_AML`

Admin не может разморозить AML-замороженный vault.

HTTP: 409 Conflict
Kind: conflict

Подробности

AML-провайдер запретил админам снимать заморозку. Для разморозки нужны более широкие полномочия или изменение настроек провайдера.

Wallet

`WALLET_ALREADY_EXISTS`

Wallet с такой комбинацией параметров уже существует.

HTTP: 409 Conflict
Kind: conflict

Подробности

Попытка создать wallet/asset для существующей пары vault+currency.

`WALLET_ASSET_NOT_FOUND`

Asset кошелька не найден.

HTTP: 404 Not Found
Kind: not_found

Подробности

Запрошенный asset отсутствует или принадлежит другому workspace.

`WALLET_CURRENCY_UNKNOWN`

Клиент указал неизвестный currency_id.

HTTP: 400 Bad Request
Kind: validation

Подробности

Currency_id из запроса не зарегистрирован в системе. Поле currency_id приходит в WebError.Details.

`WALLET_NOT_FOUND`

Кошелёк не найден.

HTTP: 404 Not Found
Kind: not_found

Подробности

Запрошенный wallet/asset отсутствует или принадлежит другому workspace.

Whitelisted Address

`WHITELISTED_ADDRESS_ALREADY_EXISTS`

Whitelisted address уже существует.

HTTP: 409 Conflict
Kind: conflict

Подробности

Указанный адрес уже добавлен в этот whitelisted-кошелёк.

`WHITELISTED_ADDRESS_NOT_FOUND`

Whitelisted address не найден.

HTTP: 404 Not Found
Kind: not_found

Подробности

Запрошенный whitelisted-адрес отсутствует или принадлежит другому кошельку.

`WHITELISTED_CURRENCY_UNKNOWN`

Клиент указал неизвестный currency_id.

HTTP: 400 Bad Request
Kind: validation

Подробности

Currency_id из запроса не зарегистрирован в системе. Поле currency_id приходит в WebError.Details.

`WHITELISTED_WALLET_ALREADY_EXISTS`

Whitelisted wallet с таким именем уже существует.

HTTP: 409 Conflict
Kind: conflict

Подробности

Имя whitelisted-кошелька должно быть уникальным в рамках workspace.

`WHITELISTED_WALLET_NOT_FOUND`

Whitelisted wallet не найден.

HTTP: 404 Not Found
Kind: not_found

Подробности

Запрошенный whitelisted-кошелёк отсутствует или принадлежит неактивному workspace.

AML

`AML_PROVIDER_INVALID_API_KEY`

Некорректный API-ключ AML-провайдера.

HTTP: 400 Bad Request
Kind: malformed

Подробности

Предоставленный API-ключ был отклонён провайдером при попытке подключения. Нужно перепроверить ключ и повторить запрос.

`AML_PROVIDER_NOT_FOUND`

AML-провайдер не найден.

HTTP: 404 Not Found
Kind: not_found

Подробности

Workspace ссылается на AML-провайдера, которого нет среди зарегистрированных в системе. Клиенту следует выбрать другого провайдера из списка доступных.

Backup

`BACKUP_NOT_FOUND`

Backup не найден.

HTTP: 404 Not Found
Kind: not_found

Подробности

Backup отсутствует, ещё не подготовлен или больше не доступен для запрошенной операции.

`BACKUP_STATUS_INCOMPATIBLE`

Статус backup не позволяет операцию.

HTTP: 409 Conflict
Kind: conflict

Подробности

Ожидался один статус, найден другой (например, для подтверждения нужен received).

`BACKUP_WORKSPACE_INACTIVE`

Workspace неактивен для backup-операции.

HTTP: 409 Conflict
Kind: conflict

Подробности

Для активного workspace разрешено создавать/проверять backup; в неактивном статусе операция отклонена.

Co-signer

`COSIGNER_PART_NOT_FOUND`

Co-signer part не найден.

HTTP: 404 Not Found
Kind: not_found

Подробности

Запрошенный part отсутствует, уже закоммичен (его конфиг очищен) или связанный pending-intent недоступен.

`COSIGNER_PART_STATUS_INVALID`

Некорректный статус part для операции.

HTTP: 409 Conflict
Kind: conflict

Подробности

Part находится в состоянии, при котором запрошенная операция недопустима (например, попытка commit без предварительного receive).

Gas station

`GAS_STATION_CANNOT_ASSIGN_SELF`

Попытка активировать auto-fuel на вольте, который сам является gas station.

HTTP: 400 Bad Request
Kind: validation

Подробности

Gas station vault не может быть источником пополнения для самого себя — выберите другой vault.

`GAS_STATION_NOT_FOUND`

Gas station или связанная конфигурация не найдены.

HTTP: 404 Not Found
Kind: not_found

Подробности

Для workspace/vault не назначена gas station, либо отсутствует asset-конфигурация в назначенной gas station.

Intent

`INTENT_BATCH_ACQUIRE_WRONG_ENDPOINT`

Batch-sign intent acquire через неверный эндпоинт.

HTTP: 400 Bad Request
Kind: validation

Подробности

Batch-sign intent должен acquire-ться через /pending-intent/{id}/acquire-sign, а не через /acquire.

`INTENT_NOT_ACQUIRABLE`

Intent нельзя acquire текущим пользователем.

HTTP: 409 Conflict
Kind: conflict

Подробности

Пользователь не подходит на роль acquire-er (нет прав либо intent адресован другому target).

`INTENT_NOT_FOUND`

Pending intent не найден.

HTTP: 404 Not Found
Kind: not_found

Подробности

Запрошенный pending intent отсутствует, отозван или принадлежит другому workspace.

`INTENT_NOT_SIGNABLE`

Intent нельзя подписать.

HTTP: 409 Conflict
Kind: conflict

Подробности

Для операции AcquireSign intent должен быть типа sign.

`INTENT_PAYLOAD_MISSING`

Payload intent отсутствует или null.

HTTP: 400 Bad Request
Kind: validation

Подробности

Тело pending intent не содержит обязательной секции intent.

`INTENT_STATUS_INVALID`

Некорректный статус intent для операции.

HTTP: 409 Conflict
Kind: conflict

Подробности

Операция требует определённого статуса (active/acquired); текущий статус другой и приходит в WebError.Details.

Transaction

`TRANSACTION_APPROVAL_INVALID`

Попытка апрува невалидным пользователем или для не-active intent.

HTTP: 403 Forbidden
Kind: forbidden

Подробности

Пользователь не входит в список approvers или intent уже завершён / отозван.

`TRANSACTION_ASSET_MISMATCH`

Source и target asset не совпадают.

HTTP: 400 Bad Request
Kind: validation

Подробности

Для перевода между внутренними кошельками источник и приёмник должны относиться к одной и той же валюте.

`TRANSACTION_BLOCKED_BY_POLICY`

Транзакция заблокирована политикой workspace.

HTTP: 403 Forbidden
Kind: forbidden

Подробности

Правила politики не разрешают эту операцию. Причина и метаданные решения едут в WebError.Details.

`TRANSACTION_INSUFFICIENT_BALANCE`

На источнике недостаточно available-баланса.

HTTP: 409 Conflict
Kind: conflict

Подробности

Available-баланс источника меньше суммы перевода (плюс комиссия, если она списывается из того же актива). В WebError.Details кладутся available и required в атомарных единицах.

`TRANSACTION_NOT_FOUND`

Транзакция не найдена.

HTTP: 404 Not Found
Kind: not_found

Подробности

Запрошенная транзакция отсутствует или принадлежит другому workspace.

`TRANSACTION_STATUS_INCOMPATIBLE`

Статус транзакции не позволяет операцию.

HTTP: 409 Conflict
Kind: conflict

Подробности

Операция требует определённого статуса (например, разморозка нужна только для frozen). Текущий статус кладётся в WebError.Details.

`TRANSACTION_TARGET_MISSING`

Не задан адрес/кошелёк назначения.

HTTP: 400 Bad Request
Kind: validation

Подробности

В запросе нужно указать либо target_address, либо target_wallet_id.

`TRANSACTION_UNFREEZE_BLOCKED_BY_AML`

Admin не может разморозить AML-замороженную транзакцию.

HTTP: 409 Conflict
Kind: conflict

Подробности

AML-провайдер запретил админам снимать заморозку транзакций.

`TRANSACTION_UPSTREAM_ERROR`

Ошибка от внешней системы обработки транзакций.

HTTP: статус наследуется от Kind, который выводится из status_code в Details
Kind: validation | not_found | conflict | unauthorized | forbidden | unavailable | internal

Подробности

Внешняя система обработки транзакций вернула не-2xx ответ. Все полезные поля upstream-ответа (status_code, error_code, error_details, transaction_id, status, expired_at) доступны через WebError.Details. Если в upstream-ответе был error_code, именно он позволяет клиенту реагировать на конкретный сценарий.

Company

`COMPANY_NOT_FOUND`

Компания не найдена.

HTTP: 404 Not Found
Kind: not_found

Подробности

Запрошенная компания отсутствует в системе.

Webhook

`WEBHOOK_LIMIT_EXCEEDED`

Превышен лимит webhooks для workspace.

HTTP: 409 Conflict
Kind: conflict

Подробности

Для workspace настроено максимально допустимое количество webhooks. Удалите неактуальные перед созданием новых.

`WEBHOOK_NOT_FOUND`

Webhook не найден.

HTTP: 404 Not Found
Kind: not_found

Подробности

Запрошенный webhook отсутствует или принадлежит другому workspace.

`WEBHOOK_SIGNING_KEY_UNAVAILABLE`

KMS-подписант не сконфигурирован.

HTTP: 503 Service Unavailable
Kind: unavailable

Подробности

Попытка получить публичный ключ для проверки подписи, но trust-сервис не настроен. Скорее всего ошибка конфигурации сервиса.

`WEBHOOK_URL_INVALID`

URL вебхука не прошёл проверку.

HTTP: 400 Bad Request
Kind: validation

Подробности

URL не парсится, использует недопустимую схему, указывает на loopback/приватную сеть или хост не резолвится. Конкретная причина едет в WebError.Details.