Перелік помилок

Коди помилок API інтеграції плагінів, відповідність статусів HTTP та troubleshooting.

Кожна відповідь з помилкою з API інтеграції плагінів використовує той самий конверт:

{
  "error": {
    "code": "quota_exceeded",
    "message_i18n": {
      "en": "Account does not have enough credits to reserve this job. Top up the credit balance.",
      "pl": "Konto nie ma wystarczającej liczby kredytów..."
    },
    "retryable": false,
    "doc_url": "https://qamera.ai/docs/plugin-api/errors/quota_exceeded"
  }
}

code стабільний між випусками — розгалужуйтесь за ним у клієнті. message_i18n є інформаційним і може еволюціонувати. retryable підказує, чи повтор з тим самим payload може спрацювати.

Коди

Код	HTTP	Retryable	Значення
`invalid_input`	400	ні	Payload запиту не пройшов валідацію
`unauthorized`	401	ні	Відсутній, неправильний або відкликаний API-ключ
`forbidden`	403	ні	Ключ не має потрібного scope
`not_found`	404	ні	Ресурс не існує або недоступний
`idempotency_conflict`	409	ні	Idempotency-Key повторно використаний з іншим payload
`job_not_cancelable`	409	ні	Завдання не в стані, що дозволяє скасування
`job_not_completed`	409	ні	Outputs запитано до завершення завдання
`batch_limit_exceeded`	400	ні	Забагато елементів у batch
`rate_limit_exceeded`	429	так	Бюджет запитів на ключ вичерпано
`quota_exceeded`	402	ні	Обліковий запис без кредитів
`concurrency_limit_exceeded`	429	так	Обліковий запис досяг ліміту одночасних завдань для провайдера
`content_policy_violation`	422	ні	Source asset або параметри порушують політику
`source_asset_unavailable`	422	ні	Не вдається отримати вказаний source asset
`low_quality_input`	422	ні	Якість source asset надто низька для надійної генерації
`output_unavailable`	410	ні	Згенерований asset видалено зі сховища
`packshot_not_approved`	422	ні	Фотозйомка не має схваленого пекшоту для продукту
`generation_failed`	502	так	Помилка upstream провайдера AI
`internal_error`	500	так	Неочікувана помилка сервера

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

Помилка, що виникла під час виконання завдання, додатково несе category, а її code походить із цієї категорії. Помилки валідації, авторизації та лімітів ніколи не досягають генератора, тож не мають category.

`category`	`code`	`retryable`
`CONTENT_POLICY`	`content_policy_violation`	ні
`INPUT_MISSING`	`source_asset_unavailable`	ні
`INPUT_NOT_READY`	`source_asset_unavailable`	так
`RATE_LIMIT`	`rate_limit_exceeded`	так
`TRANSIENT_INFRA`	`generation_failed`	так
`PROVIDER_CAPACITY`	`generation_failed`	так
`INTERNAL_BUG`	`internal_error`	ні
`PROVIDER_ACCOUNT`	`internal_error`	ні

Завдання, що зазнали невдачі до появи цієї класифікації, повідомляють generation_failed без category.

retryable для невдачі генерації описує завдання, а не запит: воно true лише тоді, коли наступна спроба вже запланована. Колонка вище — це стеля, яку допускає відповідна категорія, і її звужує власний status завдання: щойно цей статус стає кінцевим (completed, failed, cancelled, expired), конверт повідомляє false незалежно від категорії. Вебхук job.failed надсилається на переході в кінцевий стан, тож його error.retryable завжди false.

Два наслідки варто прочитати уважно:

internal_error, що виник під час генерації, ніколи не є retryable, хоча той самий код у відповіді 500 варто було б повторити — завдання не буде повторено за вас, тож повторне надсилання без змін не допоможе.
source_asset_unavailable у таблиці кодів вище позначено як не-retryable, і на рівні запиту це лишається правдою. Як результат завдання це залежить від категорії: INPUT_MISSING потребує того, що можете надати лише ви, і є остаточним, тоді як INPUT_NOT_READY означає, що ми самі ще готуємо ресурс — таке завдання повідомляє retryable: true, доки чекає, і false, коли очікування вичерпається і завдання завершиться як failed.

Тож будуйте логіку на code і category, а retryable читайте як «чи вже запланована наступна спроба», ніколи як «чи варто надіслати це ще раз».

message_i18n ніколи не містить тексту від постачальника чи внутрішньої діагностики. Будуйте логіку на code, а message_i18n показуйте людині.