Ошибки

GetQR API находится в бета-версии и доступен для отдельных рабочих пространств. До общего релиза детали могут измениться.

GetQR API использует стандартные коды состояния HTTP. Успешные запросы возвращают 2xx. Неудачные запросы возвращают 4xx или 5xx с JSON-телом, которое объясняет, что пошло не так.

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

У всех ошибок одинаковая структура: стабильный код, понятное человеку сообщение и ссылка на описание этого кода.

{
  "error": {
    "code": "unauthorized",
    "message": "Unauthorized: Invalid API key.",
    "doc_url": "https://getqr.com/account/api-docs#error-unauthorized"
  }
}

string

обязательно

Стабильный машиночитаемый код ошибки. Используйте в коде его, а не сообщение. См. Коды ошибок.

string

обязательно

Понятное человеку описание проблемы. Формулировка может меняться.

string

обязательно

Ссылка на описание кода ошибки в документации API в вашем аккаунте GetQR.

Коды ошибок

Код	Статус HTTP	Когда возникает
`bad_request`	400	Некорректный запрос: тело не является валидным JSON, в заголовке `Authorization` нет префикса `Bearer` или действие недопустимо в текущем состоянии ресурса (например, отмена завершённого массового создания).
`unauthorized`	401	API-ключ не передан или недействителен, например потому, что его перевыпустили.
`forbidden`	403	Подписка владельца рабочего пространства неактивна или ваша роль в рабочем пространстве не разрешает это действие.
`exceeded_limit`	403	Вы достигли лимита тарифа. На тарифе Single QR — создание или дублирование QR-кода, когда в рабочем пространстве он уже есть, или запуск массового создания.
`not_found`	404	Ресурс не существует или не относится к вашему рабочему пространству, эндпоинт не существует или API не включён для вашего рабочего пространства.
`method_not_allowed`	405	Эндпоинт существует, но не принимает этот HTTP-метод. Заголовок `Allow` перечисляет допустимые методы.
`conflict`	409	Запрос конфликтует с существующими данными: слаг короткой ссылки занят, запрос с тем же `Idempotency-Key` ещё выполняется, расписание пересекается с существующим или архив массового создания ещё не готов.
`invite_pending`	409	Вас пригласили в рабочее пространство, но вы ещё не присоединились. Запросы с API-ключом его не возвращают: рабочее пространство ключа — всегда то, в котором вы состоите.
`invite_expired`	410	Срок действия вашего приглашения в рабочее пространство истёк. Запросы с API-ключом его не возвращают по той же причине.
`unprocessable_entity`	422	Тело или параметры запроса не прошли валидацию. Сообщение называет поле и описывает, что с ним не так. См. Ошибки валидации.
`rate_limit_exceeded`	429	API-ключ исчерпал запросы в текущем окне. См. Ограничения частоты запросов.
`internal_server_error`	500	Что-то пошло не так на нашей стороне. Повторите запрос позже и обратитесь в поддержку, если ошибка повторяется.

Ошибки валидации

Если тело или параметры запроса не прошли валидацию, API отвечает 422. Сообщение описывает первое невалидное поле в виде <issue>: <field>: <details>:

{
  "error": {
    "code": "unprocessable_entity",
    "message": "too_big: pageSize: Max page size is 100.",
    "doc_url": "https://getqr.com/account/api-docs#error-unprocessable_entity"
  }
}

Вложенные поля записываются через точку, например link.url.

Обработка ошибок

Ветвите логику по error.code, а не по error.message.
Не повторяйте запросы с ошибками 4xx без изменений: сначала исправьте запрос. Исключения — 409 для запроса, который ещё выполняется, и 429.
При 429 подождите столько секунд, сколько указано в заголовке Retry-After. См. Ограничения частоты запросов.
Повторяйте запросы с ошибками 5xx с экспоненциальной задержкой.

Частые проблемы

Каждый запрос возвращает 404 "This endpoint is not available."

API находится в бета-версии и ещё не включён для вашего рабочего пространства.

404 "This endpoint does not exist."

Путь указан неверно. Сверьте его со страницами эндпоинтов и проверьте, что он начинается с /api/v1/.

403 "Access denied: This account does not have an active subscription."

Подписка владельца рабочего пространства закончилась. API-ключ снова заработает, как только владелец продлит подписку.

403 "API access is not available for this role."

Ваша роль в рабочем пространстве — «Читатель». Использовать API могут только владелец рабочего пространства и редакторы.

API

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

Коды ошибок

Ошибки валидации

Обработка ошибок

Частые проблемы

Что дальше

Ограничения частоты запросов

Аутентификация

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

​Коды ошибок

​Ошибки валидации

​Обработка ошибок

​Частые проблемы

​Что дальше

Ограничения частоты запросов

Аутентификация

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

Коды ошибок

Ошибки валидации

Обработка ошибок

Частые проблемы

Что дальше