Помилки

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

API GetQR використовує стандартні коди статусу 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	Запит суперечить наявним даним: slug короткого посилання зайнятий, запит із тим самим `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

Формат помилки

Коди помилок

Помилки валідації

Обробка помилок

Поширені проблеми

Що далі

Обмеження частоти запитів

Автентифікація

​Формат помилки

​Коди помилок

​Помилки валідації

​Обробка помилок

​Поширені проблеми

​Що далі

Обмеження частоти запитів

Автентифікація

Формат помилки

Коди помилок

Помилки валідації

Обробка помилок

Поширені проблеми

Що далі