> ## 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.

# Помилки

> Формат і коди помилок, які повертає API GetQR.

> [!NOTE]
>
> API GetQR перебуває в бета-версії та доступний для окремих робочих просторів. До загального релізу деталі можуть змінитися.

API GetQR використовує стандартні коди статусу 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 | Запит суперечить наявним даним: slug короткого посилання зайнятий, запит із тим самим `Idempotency-Key` ще виконується, розклад перетинається з наявним, або архів масового створення ще не готовий. |
| `invite_pending` | 409 | Вас запросили до робочого простору, але ви ще не приєдналися. Запити з API-ключем його не повертають: робочий простір ключа — завжди той, до якого ви належите. |
| `invite_expired` | 410 | Термін дії вашого запрошення до робочого простору минув. Запити з API-ключем його не повертають з тієї самої причини. |
| `unprocessable_entity` | 422 | Тіло або параметри запиту не пройшли валідацію. Повідомлення називає поле й те, що з ним не так. Див. [Помилки валідації](#помилки-валідації). |
| `rate_limit_exceeded` | 429 | API-ключ вичерпав запити для поточного вікна. Див. [Обмеження частоти запитів](https://docs.getqr.com/ua/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/ua/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/ua/api/rate-limits.md)

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


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