Skip to content
Last updated

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

Все ошибки API возвращаются в едином формате с HTTP-кодами.

Формат ответа

{
  "statusCode": 400,
  "message": "Invalid QR code format",
  "error": "Bad Request"
}

Или с массивом ошибок валидации:

{
  "statusCode": 400,
  "message": [
    "qrCode must be a string",
    "qrCode should not be empty"
  ],
  "error": "Bad Request"
}

HTTP-коды

2xx — Успех

КодОписание
200OK — запрос выполнен
201Created — ресурс создан

4xx — Ошибки клиента

КодОписаниеДействие
400Bad RequestПроверьте параметры запроса
401UnauthorizedПроверьте API-ключ
403ForbiddenIP не в whitelist или компания отключена
404Not FoundРесурс не найден
409ConflictРесурс уже существует
422Unprocessable EntityВалидация не пройдена
429Too Many RequestsRate limit превышен

5xx — Ошибки сервера

КодОписаниеДействие
500Internal Server ErrorПовторите позже, свяжитесь с поддержкой
502Bad GatewayПроблема с upstream сервисом
503Service UnavailableСервис временно недоступен
504Gateway TimeoutТаймаут внешнего сервиса

Частые ошибки

Аутентификация

{
  "statusCode": 401,
  "message": "Invalid API key",
  "error": "Unauthorized"
}

Причины:

  • Неверный API-ключ
  • Ключ был ротирован
  • Ключ отозван

Решение: Получите актуальный ключ через /auth/company/login

IP Whitelist

{
  "statusCode": 403,
  "message": "IP address not whitelisted",
  "error": "Forbidden"
}

Решение: Добавьте IP через менеджера

Котировка истекла

{
  "statusCode": 400,
  "message": "Quote expired",
  "error": "Bad Request"
}

Причина: TTL котировки 30 секунд

Решение: Создайте новую котировку через /orders/prepare

Недостаточно средств

{
  "statusCode": 400,
  "message": "Insufficient balance",
  "error": "Bad Request"
}

Решение: Пополните баланс через депозит

Rate Limit

{
  "statusCode": 429,
  "message": "Too many requests",
  "error": "Too Many Requests"
}

Решение: Уменьшите частоту запросов, используйте exponential backoff

Retry стратегия

Когда повторять

КодRetry?Стратегия
400Исправьте запрос
401Обновите ключ
403Свяжитесь с поддержкой
404Проверьте ID ресурса
429Exponential backoff
500Exponential backoff
502Подождите 30-60 секунд
503Exponential backoff
504Exponential backoff

Exponential backoff

async function fetchWithRetry(url, options, maxRetries = 3) {
  for (let attempt = 0; attempt < maxRetries; attempt++) {
    try {
      const response = await fetch(url, options);
      
      if (response.ok) {
        return response.json();
      }
      
      if (response.status < 500 && response.status !== 429) {
        // Ошибка клиента — не повторяем
        throw new Error(`Client error: ${response.status}`);
      }
      
      // Серверная ошибка или rate limit — повторяем
      const delay = Math.min(1000 * Math.pow(2, attempt), 10000);
      await new Promise(resolve => setTimeout(resolve, delay));
      
    } catch (error) {
      if (attempt === maxRetries - 1) throw error;
    }
  }
}

Логирование

Рекомендуем логировать:

function logApiError(response, requestId) {
  console.error({
    timestamp: new Date().toISOString(),
    requestId,
    statusCode: response.statusCode,
    message: response.message,
    error: response.error
  });
}

Мониторинг

Отслеживайте:

  • Частоту ошибок 4xx/5xx
  • Время ответа API
  • Rate limit hits (429)
  • Webhook delivery failures

Поддержка

При постоянных ошибках 5xx свяжитесь с поддержкой: