Ошибки, лимиты и пагинация

Обработайте ошибки, лимиты и постраничную выдачу

Код HTTP показывает, что делать дальше: исправить запрос, проверить доступ, снизить частоту или повторить попытку позже. Описание ошибки приходит в JSON.

#Формат ошибки

Обычная ошибка содержит поле detail:

401 Unauthorized

{
  "detail": "Missing API key. Provide X-API-Key header or Authorization: Bearer <key>"
}

Ошибка параметров содержит список с местом и причиной:

422 Unprocessable Entity

{
  "detail": [
    {
      "loc": ["query", "granularity"],
      "msg": "value is not a valid enumeration member; permitted: 'day', '3h'",
      "type": "type_error.enum"
    }
  ]
}

#Коды состояния

200 OK: запрос выполнен.
400 Bad Request: запрос нельзя обработать с переданными данными.
401 Unauthorized: API-ключ отсутствует или не прошёл проверку.
403 Forbidden: ключ не имеет доступа к рынку.
404 Not Found: ресурс не найден.
422 Unprocessable Entity: параметр имеет неверный тип, значение или диапазон.
429 Too Many Requests: превышён лимит запросов.
503 Service Unavailable: сервис временно недоступен.

#Лимиты и квоты

REST API и MCP-сервер входят во все тарифы и расходуют одну квоту. Месячная квота запросов зависит от тарифа проекта:

Start: 100 запросов в месяц;
Grow: 10 000 запросов в месяц;
Scale: 500 000 запросов в месяц;
Enterprise: 2 000 000 запросов в месяц.

Квоту увеличивают докупленные сущности, ключевые слова и паблишеры: каждая сущность для отслеживания добавляет 10 запросов в месяц, каждое ключевое слово добавляет 2, каждый паблишер для отслеживания добавляет 10. Правило одно для всех тарифов, а набор доступных опций зависит от тарифа.

Запрос считается так: один HTTP-вызов равен одному запросу, и каждая страница постраничной выдачи считается отдельно. Частота запросов в минуту тоже ограничена: при превышении сервис вернёт 429. В проекте можно создать до 10 API-ключей. Если квоты не хватает, подключите пакет запросов или перейдите на старший тариф: условия указаны на странице «Тарифы».

#Постраничная выдача

Большинство списков принимает limit для размера страницы и offset для числа пропущенных элементов. Точные границы указаны у каждого метода.

Вторая страница

curl "https://dstrends.com/api/v1/entities?region=us&limit=50&offset=50" \
  -H "X-API-Key: $DTR_API_KEY"

Лента v2 также поддерживает курсор. Используйте его для последовательной выгрузки новых элементов без повторов.