Довідник помилок

Усі відповіді з помилками мають однакову структуру: код статусу + машиночитний code + повідомлення для людини + необов’язкове поле field, яке вказує на проблемні вхідні дані.

Обгортка

{
  "success": false,
  "error": "Content length (5000) exceeds maximum allowed (4296 characters).",
  "code": "CONTENT_TOO_LONG",
  "field": "content"
}

Коди статусу HTTP

Статус	Значення
`200`	Успіх
`400`	Помилка перевірки — виправте вхідні дані й повторіть
`401`	Заголовок автентифікації відсутній або неправильний
`402`	Шлюз користувацьких ключів: немає плану Studio або вичерпано кредити API
`404`	Ендпоінт не знайдено
`413`	Тіло запиту завелике (>10 MB) або, через шлюз користувацьких ключів, згенерований файл понад 10 MB (`output_too_large`)
`422`	Рушій не зміг створити зчитуваний QR навіть після автовиправлення (`QR_UNSCANNABLE`), або результат перевищив би бюджет (`OUTPUT_TOO_COMPLEX`)
`429`	Ліміт запитів — див. `Retry-After`
`500`	Внутрішня помилка — зафіксуйте в журналі й повторіть
`503`	Сервер перевантажений (багато одночасних рендерів) або в провайдерів ШІ вичерпано ресурс (`AI_QUOTA_EXCEEDED`)

Помилки перевірки (400)

Код	Значення
`MISSING_REQUIRED_FIELD`	`content` (або `prompt` в ендпоінтах ШІ) порожній
`CONTENT_TOO_LONG`	Закодований вміст > 4296 символів (теоретичний максимум QR)
`INVALID_JSON`	Тіло не розбирається як JSON
`INVALID_HEX`	Рядок кольору не у форматі `#RGB`, `#RRGGBB` або `#RRGGBBAA`
`INVALID_FIELD_VALUE`	Загальна помилка — `field` підкаже, яке саме поле
`VALUE_OUT_OF_RANGE`	Числове поле поза задокументованими межами
`LOW_CONTRAST`	Контраст переднього плану й фону < 4:1; рушій не може виправити автоматично
`LOGO_TOO_LARGE`	`logoSizePercent` > 25 при ECC нижче H
`FILE_TOO_LARGE`	Завантаження multipart > 10 MB
`MULTIPART_CONFIG_MISSING`	У запиті form-data відсутнє поле `config`

Помилки автентифікації (401)

Код	Значення
`UNAUTHORIZED`	`X-RapidAPI-Proxy-Secret` відсутній або неправильний
`INVALID_INTERNAL_SIGNATURE`	Підпис HMAC від BFF не пройшов перевірку
`INTERNAL_TS_EXPIRED`	Мітка часу BFF поза вікном ±60 с
`LLM_API_KEY_INVALID`	Ключ вашого провайдера (лише в ендпоінті ШІ маркетплейсу)

Помилки шлюзу користувацьких ключів

Шлюз https://qr-branding.com/api/v1/* (Ключі API користувачів) додає власні коди в нижньому регістрі з тією самою обгорткою success / error / code:

Статус	Код	Значення
`400`	`invalid_body`	Не вдалося розібрати тіло запиту
`401`	`missing_api_key`	Немає заголовка `X-API-Key`
`401`	`invalid_api_key`	Ключ не розпізнано, відкликано або він має неправильний формат
`402`	`studio_required`	Ключ дійсний, але в обліковому записі немає активного пакета Studio. Містить посилання `docs` і `pricing`
`402`	`out_of_api_credits`	Генерація ШІ на наших ключах без залишку кредитів Studio. Містить посилання `docs` і `pricing`
`413`	`payload_too_large`	Тіло запиту понад 1 MiB
`413`	`output_too_large`	Згенерований файл більший за 10 MB. Запитайте PNG або менший `outputWidth`
`415`	`multipart_not_supported`	Шлюз приймає лише JSON

Помилки оплати

POST /api/checkout (кнопка купівлі на /pricing) відповідає { "error": "withdrawal_waiver_required" }, якщо згоди немає:

Статус	Код	Значення
`400`	`withdrawal_waiver_required`	Не позначено поле перед оплатою (згода й відмова від права на відмову від договору). Див. Ціни й кредити

Помилки генерації ШІ

Код	Значення
`AI_GENERATION_FAILED`	LLM не повернула придатної конфігурації — спробуйте чіткіший промпт
`AI_REQUEST_TIMEOUT`	Жоден провайдер резервного ланцюжка не відповів за загальні 45 с (кожен має щонайбільше 20 с). Повертає 503; повторіть за мить
`AI_QUOTA_EXCEEDED`	Усі провайдери резервного ланцюжка відмовили через квоту або ліміт витрат. Повертає 503; повтор одразу не допоможе, спробуйте пізніше
`AI_CONFIG_INVALID`	LLM повернула конфігурацію, яку рушій відхилив (рідко; повторіть із нижчою креативністю)
`INVALID_LLM_PROVIDER`	Лише маркетплейс — `llmProvider` не входить до `openai anthropic google mistral cohere groq xai deepseek qwen local`
`INVALID_LLM_MODEL`	Лише маркетплейс — `llmModel` не має формату ID моделі

Помилки бюджету результату (422)

Код Значення

OUTPUT_TOO_COMPLEX Дизайн дав би SVG або PDF понад 20 MB чи внутрішнє растрове полотно понад 5120 px на бік. Розмір SVG зростає з кількістю модулів: шаблон із короткою URL займає ~1,5 MB, із URL на 300 символів ~17 MB. Експортуйте в PNG, скоротіть вміст або виберіть простіші форми модулів

Код	Значення
`OUTPUT_TOO_COMPLEX`	Дизайн дав би SVG або PDF понад 20 MB чи внутрішнє растрове полотно понад 5120 px на бік. Розмір SVG зростає з кількістю модулів: шаблон із короткою URL займає ~1,5 MB, із URL на 300 символів ~17 MB. Експортуйте в PNG, скоротіть вміст або виберіть простіші форми модулів

Помилки сервера (500/503)

Код	Значення
`INTERNAL_ERROR`	Неочікувана помилка — повідомте нам, додавши ідентифікатор запиту
`QR_GENERATION_FAILED`	Збій у самому рушії рендерингу. Якщо відомо, містить проблемне поле
`SERVER_BUSY`	Забагато одночасних рендерів у високій роздільній здатності. Зачекайте й повторіть

Обмеження для полів

Поле	Обмеження
`content`	1–4296 символів
`prompt` (ШІ)	1–10000 символів
`creativity` (ШІ)	`0.0–1.0`
`pixelsPerModule`	`1–100`
`outputWidth` / `outputHeight`	`64–4096`
`logoSizePercent`	`3–40` (рушій м’яко обмежує до `25` при ECC H)
`moduleScale`	`0.5–1.0`
`moduleSizeVariation`	`0.0–0.15` (м’яке обмеження, вищі значення ламають сканування)
`qrShapeRadius`	`0–50`
Розмір файлу логотипа / фону	≤ 10 MB
Типи зображень логотипа / фону	PNG, JPG, GIF, BMP, WebP
Документ SVG / PDF	≤ 20 MB (`OUTPUT_TOO_COMPLEX`)
Файл через шлюз користувацьких ключів	≤ 10 MB (`output_too_large`)