Коды ошибок

При возникновении ошибки API SNABZHENETS+ возвращает стандартный ответ:

{
  "error": "VALIDATION_ERROR",
  "message": "Подробное описание ошибки",
  "statusCode": 400
}

HTTP-статусы

Статус	Значение
200	Успешный запрос
201	Ресурс создан
400	Ошибка валидации данных
401	API key отсутствует или недействителен
403	У API key нет нужного scope
404	Ресурс не найден
409	Конфликт (например, дублирование)
429	Превышен лимит запросов
422	Бизнес-логика не позволяет выполнить операцию
500	Внутренняя ошибка сервера

Коды ошибок приложения

Код	Описание
VALIDATION_ERROR	Переданные данные не прошли валидацию
UNAUTHORIZED	API key отсутствует или недействителен
FORBIDDEN	Выданный ключ не имеет нужного scope
NOT_FOUND	Запрошенный ресурс не найден
DUPLICATE_ENTRY	Запись с такими данными уже существует
rate_limited	Превышен лимит публичного Integration API
TENANT_MISMATCH	Ресурс принадлежит другому порталу
INVALID_STATUS_TRANSITION	Переход в указанный статус невозможен
INSUFFICIENT_PAYMENT	Сумма оплаты превышает остаток по счёту

Rate limit

Публичный Integration API возвращает 429, когда tenant/API-key bucket исчерпан:

{
  "statusCode": 429,
  "error": "rate_limited",
  "message": "Public API rate limit exceeded",
  "limit": 300,
  "remaining": 0,
  "resetInSeconds": 17
}

Ответ также содержит Retry-After, RateLimit-Limit, RateLimit-Remaining, RateLimit-Reset, RateLimit-Policy и совместимые X-RateLimit-* headers. Клиенту нужно дождаться Retry-After или использовать backoff.

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

Рекомендуется обрабатывать ошибки по коду:

const response = await fetch('/api/v1/integration-api/catalog-items', {
  headers: { 'X-API-Key': apiKey }
});

if (!response.ok) {
  const error = await response.json();
  if (error.statusCode === 401) {
    // Остановить запросы и запросить замену ключа у владельца портала
  }
  if (error.statusCode === 403) {
    // Не повторять запрос: согласовать отдельный минимальный scope
  }
}