Ошибки¶

Конверт ошибки¶

Любая ошибка, которую возвращает API, выглядит одинаково — три ключа:

{
  "statusCode": 422,
  "message": "INVALID_INVOICE_AMOUNT",
  "timestamp": "2026-01-14T09:00:00.000Z"
}

message — это код ошибки: идентификатор в верхнем регистре вроде INVALID_INVOICE_AMOUNT, а не фраза. Он стабилен, машиночитаем, и ветвиться нужно именно по нему. Отдельного поля code нет, и разбора по полям, что именно не так с телом запроса, тоже нет: 400 INVALID_REQUEST_BODY говорит, что тело отклонено, но не говорит, какое поле в этом виновато.

У двух ошибок есть четвёртый ключ, details. 422 NOTHING_TO_SWEEP добавляет сумму, оставшуюся на адресе, и сетевую комиссию, в которую обошлось бы её перемещение; см. свип депозитного адреса. 422 DESTINATION_NOT_ACTIVATED добавляет minAmount — наименьшую выплату, которая создаёт счёт получателя; см. вывод на RIPPLE. Других ошибок с details нет.

statusCode дублирует HTTP-статус. timestamp — момент формирования ошибки, в UTC.

Общие коды¶

Ошибка, у которой нет более точного кода, отвечает общим кодом своего статуса — например, несуществующий маршрут даёт 404 NOT_FOUND.

Незнакомый код обрабатывайте по его статусу, по таблице из раздела повторы.

По статусам¶

400 — запрос сформирован неверно¶

400 повторять бессмысленно: запрос отклонят ровно так же.

401 — вас не опознали¶

Все четыре причины намеренно неразличимы — по ответу не понять, какая сработала.

403 — опознали, но не разрешили¶

Обратите внимание на разницу между PERMISSION_DENIED и 404: существующий, но не ваш id даёт 403, а id, которого нет нигде, — 404. Поэтому 403 на GET подтверждает, что ресурс существует.

404 — ничего нет¶

Две выделенные строки — это ошибки несоответствия, поданные как «объект не найден»: настоящий paymentId под чужим invoiceId даст «платёж не найден», а настоящий tokenId в паре не с той chainId — «токен не найден». Прежде чем решить, что id неверен, проверьте пару.

WALLET_NOT_FOUND — единственное исключение из правила «чужое — это 403» выше: свип адреса другого мерчанта даёт 404, так что ответ не подтверждает, что такой id существует.

409 — уже существует¶

GET /api/v1/invoices?externalId=order-1043&limit=1

422 — корректно, но недопустимо¶

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

422 без изменений повторять бессмысленно: должно поменяться либо состояние, либо сам запрос.

5xx — запрос не выполнен на нашей стороне¶

Любой 5xx отвечает INTERNAL_ERROR. Код не говорит, что именно сломалось; статус говорит, где примерно.

Повторы¶

Используйте экспоненциальную задержку с джиттером и ограничивайте число попыток. Бесконечные повторы 502 во время сбоя внешнего сервиса только добавляют ему нагрузки.

Пример обработчика¶

resp = requests.post(url, headers=headers, json=body, timeout=30)

if resp.ok:
    return resp.json()

err = resp.json()
message = err.get("message")

if message == "INVOICE_EXTERNAL_ID_ALREADY_EXISTS":
    return fetch_invoice_by_external_id(body["externalId"])   # для вас это не ошибка
if message == "MERCHANT_BLOCKED":
    raise AccountBlocked()                                     # позовите дежурного
if resp.status_code >= 500:
    raise Retryable(message)                                   # задержка и новая попытка
raise Permanent(f"{resp.status_code} {message}")               # логируйте весь конверт

В каждой ветке пишите в лог весь конверт вместе с timestamp: именно по нему поддержка находит конкретный запрос.