Ошибки API

Каждый эндпоинт API StatusRadar возвращает JSON. При неудаче вы получаете HTTP-статус не-2xx плюс тело ошибки в формате JSON. Эта страница документирует форму тела ошибки, коды статусов, используемые API, как сообщаются ошибки валидации и как ведёт себя ограничение частоты запросов.

Форма ответа с ошибкой

Ошибки API возвращают единообразную JSON-обёртку. HTTP-код статуса несёт категорию; тело несёт человекочитаемое сообщение и, для ошибок валидации, карту по каждому полю.

{
  "success": false,
  "message": "Validation failed",
  "errors": {
    "name": "Name is required",
    "type": "Invalid monitor type"
  }
}

Успешный ответ использует зеркальную обёртку, так что вы можете ветвиться по success:

{
  "success": true,
  "message": "Success",
  "data": { }
}

Всегда проверяйте флаг success (или HTTP-статус), а не предполагайте, что тело — 2xx. Полезная нагрузка успешного вызова находится под data.

Коды статусов

API использует стандартные HTTP-коды статусов.

400 Bad Request

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

{
  "success": false,
  "message": "Invalid JSON input",
  "errors": {}
}

Убедитесь, что запросы POST/PUT отправляют Content-Type: application/json и валидное тело JSON.

401 Unauthorized

Возвращается, когда учётные данные отсутствуют или недействительны. Обратите внимание, что схемы аутентификации различаются в зависимости от поверхности API — User и Probe API используют Authorization: Bearer <token>, OTLP использует X-App-Token, а RUM использует параметр запроса api_key. Отправка неверной схемы на поверхность возвращает 401.

{
  "success": false,
  "message": "Unauthorized",
  "errors": {}
}

Полную таблицу «схема на поверхность» и типичные причины см. в разделе Аутентификация.

403 Forbidden

Вы аутентифицированы, но не имеете разрешения. Типичные случаи:

• Ваша командная роль не обладает необходимой возможностью (например, viewer пытается создать монитор — см. Команды).
• Достигнута квота тарифа (например, лимит серверов).
• Ресурс принадлежит другой команде или probe.

{
  "success": false,
  "message": "Server limit reached. Please upgrade your plan to add more servers.",
  "errors": {}
}

404 Not Found

Ресурс не существует, либо он существует, но не принадлежит вашей текущей команде. Из соображений приватности ресурсы за пределами вашей команды сообщаются как не найденные, а не как запрещённые.

{
  "success": false,
  "message": "Monitor not found",
  "errors": {}
}

500 Internal Server Error

Непредвиденная ошибка на стороне сервера. message может включать краткую причину. Их безопасно повторять после короткой задержки; если они сохраняются, обратитесь в поддержку.

{
  "success": false,
  "message": "Failed to create monitor",
  "errors": {}
}

Ошибки валидации (422)

Когда запрос является синтаксически валидным JSON, но не проходит валидацию полей, API возвращает 422 с message: "Validation failed" и объектом errors, сопоставляющим каждое недопустимое поле с сообщением. Несколько полей могут не пройти валидацию одновременно.

curl -X POST https://api.statusradar.dev/v1/monitors \
  -H "Authorization: Bearer YOUR_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"name":"","type":"smtp"}'

{
  "success": false,
  "message": "Validation failed",
  "errors": {
    "name": "Name is required",
    "type": "Invalid monitor type",
    "target": "Target is required"
  }
}

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

• name — обязательно.
• type — должно быть одно из http, https, ping, tcp, ssl, dns.
• target — обязательно, и для http/https оно должно пройти валидацию URL (неверный URL возвращает 422 с errors.target, описывающим проблему).

Полный список полей по каждому типу монитора см. в разделе Мониторы.

Ограничение частоты запросов (429)

Запросы к API ограничены по частоте на каждый идентификатор (токен плюс IP клиента). Лимит API по умолчанию — 60 запросов за 60-секундное окно. Его превышение возвращает HTTP 429:

{
  "success": false,
  "message": "Too many requests. Please try again later."
}

Лимиты отслеживаются в фиксированном 60-секундном окне. Другие действия имеют собственные выделенные лимиты (например, вход — 5 за 15 минут, а регистрация — 3 в час).

Обработка 429

• Используйте экспоненциальную задержку. При 429 подождите перед повторной попыткой и увеличивайте задержку при повторных сбоях (например, 1с, 2с, 4с).
• Кэшируйте ответы. Избегайте опроса одного и того же эндпоинта чтения в тесном цикле; кэшируйте результаты на стороне клиента, где это возможно.
• Группируйте запросы, где можете. Предпочитайте эндпоинты списков множеству вызовов по отдельным ресурсам.

# Example: simple exponential backoff on 429 / 5xx
attempt=0
until response=$(curl -fsS -w '%{http_code}' -o /tmp/body \
  -H "Authorization: Bearer $STATUSRADAR_TOKEN" \
  https://api.statusradar.dev/v1/monitors) || [ "$attempt" -ge 5 ]; do
  attempt=$((attempt + 1))
  sleep $((2 ** attempt))
done

Чек-лист обработки ошибок

• Ветвитесь по флагу success (или HTTP-статусу), никогда — по наличию data.
• Читайте errors для деталей на уровне полей в ответах 422 и показывайте их пользователю.
• Относитесь к 401/403 как к неповторяемым: исправьте учётные данные или разрешение, не зацикливайтесь.
• Относитесь к 429 и 5xx как к повторяемым: используйте задержку и повторяйте с ограниченным числом попыток.
• Отправляйте Content-Type: application/json во всех запросах POST/PUT, чтобы избежать 400.

Дальнейшие шаги

• Обзор API — поверхности, базовые URL и соглашения
• Аутентификация — схемы токенов и причины 401
• Мониторы — поля и правила валидации по каждому типу монитора
• Инциденты — чтение данных об инцидентах
• Status-страницы — чтение данных status-страниц