Ошибки

API использует стандартные HTTP-коды. Коды 2xx означают успех, 4xx — ошибку в запросе, 5xx — ошибку на стороне Pingera.

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

Тело ответа с ошибкой — JSON-объект с двумя полями:

{
  "code": "not_found",
  "message": "API token not found"
}

Поле	Тип	Описание
code	string	Машиночитаемый код ошибки. Используйте его в логике обработки.
message	string или object	Описание ошибки на английском языке. Для ошибок валидации — объект с ошибками по полям.

Текст message предназначен для людей и может меняться. Не стройте логику на его содержимом — опирайтесь на HTTP-код и code.

HTTP-коды

HTTP	Значение	Типичные code	Повторять запрос?
400	Некорректный запрос	bad_request, validation_error	Нет, исправьте запрос
401	Не пройдена аутентификация	invalid_token, token_expired, authentication_required, not_authorized	Нет, проверьте ключ
402	Ограничение тарифа	см. Ограничения тарифа	Нет, нужен другой тариф
403	Недостаточно прав	insufficient_permissions, forbidden, unauthorized	Нет
404	Ресурс не найден	resource_not_found, not_found	Нет
405	Метод не поддерживается	method_not_allowed	Нет
422	Ошибка валидации данных	validation_error, unprocessable_entity	Нет, исправьте данные
429	Превышен лимит запросов	—	Да, с задержкой
500	Внутренняя ошибка	internal_server_error, server_error	Да, с задержкой
502, 503, 504	Сервис временно недоступен	—	Да, с задержкой

Ресурсы другой организации недоступны: при обращении к ним API вернёт 403 или 404.

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

Если тело запроса не прошло проверку, API вернёт 422 и перечислит ошибки по каждому полю в message.fields:

{
  "code": "validation_error",
  "message": {
    "fields": {
      "name": ["Missing data for required field."]
    }
  }
}

Ошибки, которые относятся к сочетанию нескольких полей, приходят под ключом _schema:

{
  "code": "validation_error",
  "message": {
    "fields": {
      "_schema": ["password_protected and viewers_must_be_team_members cannot both be true. A page can be either password-protected OR private to team members, but not both."]
    }
  }
}

Некоторые проверки выполняются после разбора запроса. В этом случае API вернёт 400 с текстовым message:

{
  "code": "bad_request",
  "message": "400 Bad Request: Environment variable names must be unique"
}

Ограничения тарифа (402)

Если операция превышает лимиты вашего тарифа, API вернёт 402 Payment Required. Формат ответа отличается от остальных ошибок: вместо code в ответе есть поле limit с названием лимита.

{
  "limit": "statuspages",
  "message": "Plan limit reached for statuspages. Current plan allows 1 statuspages."
}

limit	Причина
no_plan	У организации нет активного тарифа.
checks_count	Достигнут лимит количества проверок и пульсаров.
check_interval	Интервал проверки меньше минимального для тарифа.
credits	Недостаточно кредитов для операции.
statuspages	Достигнут лимит количества Статус Страниц.
subscribers	Достигнут лимит подписчиков Статус Страницы.
domain	Тариф не поддерживает собственный домен для Статус Страницы.
email_domain	Тариф не поддерживает отправку писем с собственного домена.
template	Тариф не поддерживает выбор шаблона Статус Страницы.
css	Тариф не поддерживает настройку цветов Статус Страницы.
password_protection	Тариф не поддерживает защиту Статус Страницы паролем.

При нехватке кредитов ответ содержит дополнительные поля:

{
  "limit": "credits",
  "code": "credit_limit_exceeded",
  "message": "Credit limit exceeded. Current usage: 9990/10000 credits. This operation requires 20 credits.",
  "current_usage": 9990,
  "credit_limit": 10000,
  "operation_cost": 20
}

Текущее использование лимитов можно посмотреть в разделе Подписка.

Превышение лимита запросов (429)

При превышении лимитов запросов API вернёт 429 Too Many Requests. Этот ответ формирует балансировщик, поэтому его тело — не JSON в описанном выше формате. Проверяйте HTTP-код, а не тело ответа.

Повтор запросов

• Повторяйте запросы только при 429, 5xx и сетевых ошибках.
• Используйте экспоненциальную задержку: например, 1, 2, 4, 8 секунд, добавив к ней случайную составляющую.
• Ограничьте число попыток, например пятью.
• API не поддерживает ключи идемпотентности. Если POST завершился сетевой ошибкой или таймаутом, ресурс мог быть создан — перед повтором проверьте это запросом GET.

Пример на Python:

import random
import time

import requests

RETRYABLE = {429, 500, 502, 503, 504}


def request_with_retry(method, url, api_key, attempts=5, **kwargs):
    headers = {"Authorization": api_key}
    for attempt in range(attempts):
        try:
            response = requests.request(method, url, headers=headers, timeout=30, **kwargs)
        except requests.ConnectionError:
            response = None
        if response is not None and response.status_code not in RETRYABLE:
            return response
        if attempt < attempts - 1:
            time.sleep(2 ** attempt + random.random())
    return response