Ошибки и коды состояния

API finlight использует общепринятые коды состояния HTTP для обозначения результата запроса. Статус 2xx означает успех; 4xx — запрос отклонён (обычно это можно исправить); 5xx — проблема на нашей стороне. Каждая ошибка возвращает тело JSON с описанием того, что пошло не так.

Примечание. Запросы REST и WebSocket аутентифицируются заголовком X-API-KEY. Отсутствующий или недействительный ключ возвращает 401. (Аутентификация доставки вебхуков — заголовки, которые finlight отправляет на ваш эндпоинт, — это отдельная вещь; см. Аутентификация вебхуков.)

Коды состояния кратко

400 — Bad Request

Возвращается, когда параметры запроса или тело запроса не проходят валидацию, либо когда строка query использует недопустимый синтаксис на уровне полей.

Недопустимый параметр:

{
  "statusCode": 400,
  "message": ["pageSize must not be greater than 100"],
  "error": "Bad Request"
}

Недопустимый синтаксис query (POST /v2/articles):

{
  "statusCode": 400,
  "message": [
    {
      "property": "query",
      "constraints": { "query": "Invalid query syntax near 'ticker:'" }
    }
  ],
  "error": "Bad Request"
}

Правильный синтаксис query см. в Расширенном построении запросов.

401 — Unauthorized

Заголовок X-API-KEY отсутствует, имеет неверный формат или не является действительным ключом.

{
  "statusCode": 401,
  "message": "Unauthorized"
}

Получите или смените ключ в панели управления finlight.

403 — Forbidden

Запрос аутентифицирован, но ваш тариф не включает запрошенную возможность — например, запрос полного содержимого статьи на тарифе, который его не включает.

{
  "statusCode": 403,
  "message": "Your subscription does not allow calling the extended article content"
}

О том, какие возможности включает каждый тариф, см. в разделе Ограничения скорости и квоты.

404 — Not Found

Запрошенный ресурс не существует — чаще всего это GET /v2/articles/by-link со ссылкой link, которую finlight не проиндексировал.

{
  "statusCode": 404,
  "message": "Article not found"
}

422 — Unprocessable Entity

Некоторые эндпоинты проверяются глобальным валидатором, который возвращает карту ошибок с ключами по полям. Каждый ключ — это поле с ошибкой; значение перечисляет нарушенные ограничения.

{
  "status": 422,
  "errors": {
    "language": "language must be a string"
  }
}

Примечание. Сбои валидации могут проявляться как 400 (на эндпоинтах статей) или 422 (глобальный валидатор) в зависимости от маршрута — оба означают неверный запрос. Проверьте тело, чтобы узнать, какое поле дало сбой.

429 — Too Many Requests

Вы превысили один из лимитов использования. Есть два разных случая, у каждого своё сообщение:

Превышена месячная квота запросов:

{
  "statusCode": 429,
  "message": "Throttling Exception: Exceeded token limit of 5000 for the current period."
}

Превышена пиковая (краткосрочная) скорость:

{
  "statusCode": 429,
  "message": "Throttling Exception: Exceeded rate limit of 10 requests per 10 seconds."
}

Примечание. finlight в настоящее время не возвращает заголовки Retry-After или ограничения скорости. При пиковом 429 сделайте паузу и повторите примерно через 10 секунд. При 429 по месячной квоте запросы снова начнут проходить в начале следующего расчётного периода (или после повышения тарифа). См. Ограничения скорости и квоты.

500 — Internal Server Error

На стороне finlight произошла непредвиденная ошибка. Они временные — повторите с экспоненциальной задержкой, а если проблема сохраняется, обратитесь через Поддержку.

{
  "statusCode": 500,
  "message": "Internal server error"
}

Как правильно обрабатывать ошибки

• Всегда сначала проверяйте код состояния, затем читайте тело JSON для подробностей.
• 4xx (кроме 429) — это ваша ошибка: исправьте запрос; повтор без изменений не поможет.
• 429 и 5xx можно повторять: используйте экспоненциальную задержку. Для пикового 429 достаточно ~10 с.
• Ошибки WebSocket приходят как серверное сообщение error в сокете, а не как HTTP-статус — см. Основы WebSocket.
• Сбои доставки вебхуков (на ваш эндпоинт) отслеживаются в панели управления, а не возвращаются вам синхронно — см. Тестирование вебхуков.