> ## Documentation Index
> Fetch the complete documentation index at: https://docs.getqr.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Ошибки

> Формат ошибок и коды, которые возвращает GetQR API.

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

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

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

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

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

**error.code** `string` *required*

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

**error.message** `string` *required*

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

**error.doc\_url** `string` *required*

Ссылка на описание кода ошибки в документации 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-ключ исчерпал запросы в текущем окне. См. [Ограничения частоты запросов](https://docs.getqr.com/ru/api/rate-limits.md). |
| `internal_server_error` | 500 | Что-то пошло не так на нашей стороне. Повторите запрос позже и обратитесь в поддержку, если ошибка повторяется. |

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

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

```json theme={null}
{
  "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`. См. [Ограничения частоты запросов](https://docs.getqr.com/ru/api/rate-limits.md#превышение-лимита).
* Повторяйте запросы с ошибками `5xx` с экспоненциальной задержкой.

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

> [accordion] Каждый запрос возвращает 404 "This endpoint is not available."
>
> API находится в бета-версии и ещё не включён для вашего рабочего пространства.

> [accordion] 404 "This endpoint does not exist."
>
> Путь указан неверно. Сверьте его со страницами эндпоинтов и проверьте, что он начинается с `/api/v1/`.

> [accordion] 403 "Access denied: This account does not have an active subscription."
>
> Подписка владельца рабочего пространства закончилась. API-ключ снова заработает, как только владелец продлит подписку.

> [accordion] 403 "API access is not available for this role."
>
> Ваша роль в рабочем пространстве — «Читатель». Использовать API могут только владелец рабочего пространства и редакторы.

## Что дальше

> [card] [Ограничения частоты запросов](https://docs.getqr.com/ru/api/rate-limits.md)

> [card] [Аутентификация](https://docs.getqr.com/ru/api/authentication.md)


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.