Коди помилок

API Qamera AI використовує стандартні HTTP-коди статусу для позначення результату кожного запиту. Успішні запити повертають 200. Відповіді з помилками містять JSON-тіло з полем error, що описує проблему.

Формат відповіді

Усі відповіді з помилками мають таку структуру:

{
  "error": "A human-readable description of the problem."
}

Коди статусу

200 OK

Запит оброблено успішно. Тіло відповіді містить запитані дані або підтвердження виконаної дії.

400 Bad Request

У тілі запиту відсутні обов'язкові поля, містяться недійсні значення або воно має неправильний формат.

{
  "error": "Validation failed: 'productId' is required."
}

Поширені причини:

• Відсутні обов'язкові поля в тілі POST-запиту.
• Недійсні типи полів (наприклад, рядок замість очікуваного числа).
• Неправильний формат JSON.

401 Unauthorized

API key відсутній, недійсний, прострочений або відкликаний.

{
  "error": "Invalid API key."
}

Поширені причини:

• Не надано заголовок X-Api-Key або Authorization.
• Ключ було відкликано або минув термін його дії.
• Друкарська помилка у значенні ключа.

402 Payment Required

На акаунті, пов'язаному з API key, недостатньо кредитів для виконання запитаної операції.

{
  "error": "Insufficient credits. Required: 5, available: 2."
}

Що робити:

• Придбайте додаткові кредити або кредитний пакет у налаштуваннях білінгу вашого робочого простору.
• Перевірте поточний баланс перед надсиланням запитів на генерацію.

403 Forbidden

API key не має необхідного scope для цього ендпоінта.

{
  "error": "Missing required scope: 'content.register'."
}

Поширені причини:

• Ключ було видано без scope, необхідного для запитаної дії.
• Спроба виконати POST-операцію ключем, який має лише scope content.read.

404 Not Found

Запитаний ресурс не існує, або ваш акаунт не має до нього доступу.

{
  "error": "Product not found."
}

Поширені причини:

• Некоректний ID ресурсу в URL.
• Ресурс належить іншому акаунту.
• Ресурс було видалено.

429 Too Many Requests

API key перевищив ліміт запитів — 60 запитів на хвилину.

{
  "error": "Too many requests. Please retry after a short delay."
}

Що робити:

• Зачекайте перед повторною спробою. Використовуйте експоненціальне відступання з jitter.
• Дивіться сторінку Обмеження запитів для детальних стратегій повторних спроб.

500 Internal Server Error

На сервері сталася непередбачена помилка.

{
  "error": "An internal error occurred. Please try again later."
}

Що робити:

• Повторіть запит після невеликої затримки.
• Якщо помилка повторюється, зверніться до служби підтримки, вказавши деталі запиту та приблизний час.

502 Bad Gateway

Зовнішній сервіс, від якого залежить API, повернув неочікувану відповідь.

{
  "error": "External service returned an unexpected response."
}

Поширені причини:

• Нижчестоящий сервіс ШІ-генерації тимчасово недоступний.
• Мережеві проблеми між Qamera AI та постачальниками сервісів.

Що робити:

• Повторіть спробу через кілька секунд. Ці помилки зазвичай тимчасові.

503 Service Unavailable

Немає активного генератора контенту для обробки запиту.

{
  "error": "No active generator available. Please try again later."
}

Поширені причини:

• Усі робочі процеси генерації офлайн або на обслуговуванні.
• Тимчасові проблеми з потужністю під час пікового навантаження.

Що робити:

• Повторіть спробу через 30–60 секунд.
• Перевірте сторінку статусу Qamera AI щодо поточних інцидентів.

Зведена таблиця

Категорії невдач завдань

Коди вище описують, чи вдався ваш запит. Завдання генерації — це інше: його надсилання завершується одразу кодом 200, а сама робота відбувається пізніше. Завдання, яке зазнає невдачі згодом, повідомляється всередині успішної відповіді, а не як помилка HTTP.

Коли ви опитуєте GET /api/external/orders/:id, кожне завдання несе два поля, що описують невдачу:

• errorCategory — фіксоване значення з таблиці нижче. Будуйте логіку на ньому.
• errorHint — одне речення з поясненням категорії та що робити. Показуйте його людині, не парсіть.

Обидва дорівнюють null для успішних завдань і для невдач, записаних до появи цієї класифікації.

TRANSIENT_INFRA, RATE_LIMIT, PROVIDER_CAPACITY та INPUT_NOT_READY повторюються автоматично, тож завдання з такою категорією може все одно завершитися успішно — сприймайте їх як інформацію про хід роботи, а не як остаточний результат. Дійте лише тоді, коли замовлення перестане змінюватися, а status завдання дорівнює failed. Категорія залишається в рядку й після цього, тож читайте її разом зі status: те саме INPUT_NOT_READY означає очікування при retry_pending і відмову після очікування при failed. errorHint каже, який це випадок.

Необроблені повідомлення від постачальників навмисно не розкриваються. Вони містять назви постачальників і деталі внутрішніх систем, які змінюються без попередження — інтеграції, що їх парсили, ламалися за кожної зміни постачальника. Стабільним контрактом є категорія.