Ошибки API

API Relavio возвращает стандартные HTTP-статусы и JSON-ответы. Для успешных запросов используется общий envelope с полями data и error. Ошибки авторизации и валидации возвращаются в формате Laravel.

Успешный ответ

{
  "data": {
    "search_id": "search-123",
    "session_id": "session-123",
    "products": []
  },
  "error": {
    "code": 0,
    "message": ""
  }
}

Если error.code равен 0, запрос выполнен успешно.

Основные HTTP-статусы

Статус	Значение	Когда возникает
200	OK	Запрос выполнен успешно.
401	Unauthorized	API-ключ отсутствует или неверный.
402	Payment Required	Превышен бесплатный лимит или недостаточно баланса.
422	Validation Error	Тело запроса не прошло валидацию.
500	Server Error	Внутренняя ошибка сервера.

401 Unauthorized

Возникает, если не передан API-ключ или ключ не найден.

Ключ отсутствует:

{
  "message": "Missing api_key header."
}

Ключ неверный:

{
  "message": "Invalid api_key header."
}

Что проверить:

• заголовок называется api-key или api_key;
• ключ скопирован полностью;
• ключ относится к нужному магазину;
• магазин существует и не удален.

402 Payment Required

Возникает для платных endpoint-ов, если бесплатный лимит исчерпан или на балансе недостаточно средств.

Превышен бесплатный месячный лимит API-запросов:

{
  "message": "Free monthly API request limit exceeded. Top up your balance to continue with pay-as-you-go billing."
}

Недостаточно средств для списания:

{
  "message": "Insufficient balance for pay-as-you-go API request."
}

Что сделать:

• проверьте баланс;
• пополните счет;
• проверьте лимиты тарифа;
• уменьшите количество тестовых запросов.

422 Validation Error

Возникает, если payload не соответствует правилам endpoint-а.

Пример:

{
  "message": "The query field is required.",
  "errors": {
    "query": [
      "The query field is required."
    ]
  }
}

Частые причины:

• отсутствует обязательное поле query для /api/v1/search;
• filters передан не объектом;
• event_type не входит в список допустимых событий;
• currency не состоит из 3 символов;
• position, page или quantity меньше 1.

Ошибки Search API

Для /api/v1/search поле query обязательно и должно быть строкой.

Минимальный корректный запрос:

{
  "query": "iphone"
}

Ошибки Suggest API

Для /api/v1/search/suggests поле query может быть пустым, но если передано, оно должно быть строкой.

{
  "query": "iph",
  "session_id": "session-123"
}

Ошибки Events API

Для /api/v1/search/events обязательно поле event_type.

Допустимые значения:

• click;
• add_to_cart;
• purchase.

Пример корректного события:

{
  "event_type": "click",
  "external_id": "product-123",
  "product_name": "iPhone 15"
}

Рекомендации по обработке ошибок

• Проверяйте response.ok перед чтением успешного результата.
• Логируйте HTTP-статус и тело ошибки.
• Для 401 проверяйте API-ключ.
• Для 402 показывайте администратору сообщение о балансе или лимитах.
• Для 422 исправляйте payload до повторной отправки.
• Не повторяйте бесконечно запросы, которые вернули 401, 402 или 422.

Пример обработки в JavaScript

const response = await fetch('/api/v1/search', {
    method: 'POST',
    headers: {
        Accept: 'application/json',
        'Content-Type': 'application/json',
        'api-key': 'YOUR_API_KEY',
    },
    body: JSON.stringify({ query: 'iphone' }),
});

const payload = await response.json();

if (!response.ok) {
    console.error('Relavio API error', response.status, payload);
    return;
}

console.log(payload.data);