Ошибки¶

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

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

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

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

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

Два исключения¶

Конверт действует везде, кроме двух мест.

Несуществующий курс отвечает иначе, потому что ошибку выбрасывает сам шлюз:

{ "statusCode": 404, "message": "Rate not found", "error": "Not Found" }

Текстовый message, лишний ключ error, timestamp отсутствует. Так делает только GET /api/v1/tokens/rate.

Недоступный внешний сервис даёт голое:

{ "statusCode": 500, "message": "Internal server error" }

Значит, запрос не дошёл до места, где его классифицировали бы. Считайте такой ответ повторяемым.

По статусам¶

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

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

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

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

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

Разницу между PermissionDeniedError и 404 стоит запомнить: существующий, но не ваш id даёт 403, а id, которого нет нигде, — 404. Из чего следует, что 403 на GET подтверждает: ресурс существует.

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

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

MerchantWalletForChainTypeNotFoundError — проблема конфигурации, а не запроса: она означает, что никто не настроил в кабинете кошелёк для выплат в этом семействе. Повтор её не исправит.

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

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

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

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

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

502 — сбой внешнего сервиса¶

Повторы¶

Используйте экспоненциальную задержку с джиттером и ограничивайте число попыток. Клиент, который бесконечно повторяет 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 == "InvoiceWithExternalIdAlreadyExistsError":
    return fetch_invoice_by_external_id(body["externalId"])   # для вас это не ошибка
if message == "MerchantIsBlockedError":
    raise AccountBlocked()                                     # позовите дежурного
if resp.status_code >= 500:
    raise Retryable(message)                                   # задержка и новая попытка
raise Permanent(f"{resp.status_code} {message}")               # логируйте весь конверт

В каждой ветке пишите в лог весь конверт вместе с timestamp. Процитировав его, вы превратите разговор с поддержкой об одном запросе в короткий.