Обработка ошибок

Все ошибки API приходят в одном формате. Ветвитесь по полю errorCode: оно есть в каждом ответе с ошибкой и не меняется, а текст message может уточняться.

{
  "statusCode": 400,
  "error": "Bad Request",
  "errorCode": "QR_INVALID",
  "message": "QR код недействителен (код: RQ00010)",
  "details": { "nspkCode": "RQ00010" },
  "path": "/orders/prepare",
  "timestamp": "2026-10-03T10:15:42.120Z",
  "requestId": "439436bd-201c-4084-9063-58cfa2cd40ad"
}

Ошибка валидации тела или параметров:

{
  "statusCode": 400,
  "error": "Bad Request",
  "errorCode": "VALIDATION_ERROR",
  "message": [
    "qrCode must be a string",
    "qrCode should not be empty"
  ],
  "path": "/orders/prepare",
  "timestamp": "2026-10-03T10:15:42.120Z",
  "requestId": "6b0b7c2e-4f5a-4d7e-9f10-2a3b4c5d6e7f"
}

Лишние поля в теле запроса не вызывают ошибку — они просто игнорируются.

Несколько ошибок делят один errorCode, а причину уточняют в начале message, до двоеточия:

Каждый ответ с ошибкой содержит requestId — и в теле, и в заголовке X-Request-Id. Если вы сами передали заголовок X-Request-Id, вернётся ваше значение: так запрос удобно связать со своими логами. Иначе мы генерируем UUID.

Собственного ограничения частоты запросов у API нет. Код 429 возможен только как ответ внешнего сервиса, который API передаёт как есть, — в операциях с выплатами и кошельками пользователей. Повторите запрос позже.

Часть операций выполняют внешние сервисы: эквайер карт, сервис кошельков пользователей, сервис выплат. Их ошибки API передаёт с тем же HTTP-кодом и общим errorCode (UNAUTHORIZED, FORBIDDEN, NOT_FOUND, CONFLICT, UNPROCESSABLE, BAD_GATEWAY), а источник виден по началу message: bridge 400: … — эквайер карт, p2p 409: … — сервис выплат, Wallet backend error: 404 — сервис кошельков. Такой 401 или 403 не значит, что неверен ваш ключ.

Список кодов пополняется. Неизвестный errorCode обрабатывайте как общую ошибку для своего statusCode.

Что значит 502 для разных операций:

• POST /orders/accept/{id} — ордер не создан и средства не заморожены. Можно повторить, пока котировка не истекла. Если 502 повторяется для одной и той же котировки, платёж этому получателю не принимается — повтор не поможет. Недоступность платёжного сервиса может прийти и как 500 — ордер в этом случае тоже не создан.
• POST /cards/request — эквайер не ответил, исход неизвестен: карта могла выдаться. Резерв возвращается сразу, а выданная карта придёт вебхуком card.assigned. Повторяйте только с тем же Idempotency-Key.
• POST /cards/recharge отвечает 502, только если эквайер не ответил при расчёте стоимости, — списания тогда не было. Если сбой случился при самом пополнении, ответ — 201 со статусом pending, а пополнение досверяется автоматически, см. Пополнение карты.

async function fetchWithRetry(url, options, maxRetries = 3) {
  for (let attempt = 0; ; attempt++) {
    const response = await fetch(url, options);
    if (response.ok) return response;

    const body = await response.json().catch(() => null);
    const retriable = response.status === 500 || response.status === 503;

    if (!retriable || attempt === maxRetries) {
      const err = new Error(body?.message ?? `HTTP ${response.status}`);
      err.errorCode = body?.errorCode;
      err.requestId = body?.requestId ?? response.headers.get('x-request-id');
      throw err;
    }

    const delay = Math.min(1000 * 2 ** attempt, 10_000);
    await new Promise((resolve) => setTimeout(resolve, delay));
  }
}

Сохраняйте requestId, errorCode и path каждой ошибки — по requestId поддержка найдёт запрос у себя:

function logApiError(body) {
  console.error({
    requestId: body.requestId,
    errorCode: body.errorCode,
    statusCode: body.statusCode,
    path: body.path,
    message: body.message,
  });
}

При повторяющихся ошибках 5xx напишите в @lumo_support_bot и укажите requestId, время, эндпоинт и тело запроса (без ключа).