Lista błędów

Kody błędów API integracji wtyczek, mapowanie statusów HTTP i troubleshooting.

Każda odpowiedź błędu z API integracji wtyczek używa tej samej koperty:

{
  "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 jest stabilny między wydaniami — rozgałęziaj na nim w kliencie. message_i18n jest informacyjny i może ewoluować. retryable doradza, czy ponowienie z tym samym payloadem może się udać.

Kody

Kod	HTTP	Retryable	Znaczenie
`invalid_input`	400	nie	Payload zapytania nie przeszedł walidacji
`unauthorized`	401	nie	Brakujący, błędny lub odwołany klucz API
`forbidden`	403	nie	Klucz nie ma wymaganego uprawnienia
`not_found`	404	nie	Zasób nie istnieje lub jest niedostępny
`idempotency_conflict`	409	nie	Idempotency-Key użyty ponownie z innym payloadem
`job_not_cancelable`	409	nie	Zadanie nie jest w stanie pozwalającym na anulowanie
`job_not_completed`	409	nie	Wyniki zażądane przed ukończeniem zadania
`batch_limit_exceeded`	400	nie	Za dużo elementów w batchu
`rate_limit_exceeded`	429	tak	Wyczerpany budżet zapytań na klucz
`quota_exceeded`	402	nie	Konto bez kredytów
`concurrency_limit_exceeded`	429	tak	Konto osiągnęło limit równoczesnych zadań dla providera
`content_policy_violation`	422	nie	Źródłowy asset lub parametry łamią politykę
`source_asset_unavailable`	422	nie	Nie można pobrać wskazanego source asset
`low_quality_input`	422	nie	Jakość source asset za niska dla wiarygodnej generacji
`output_unavailable`	410	nie	Wygenerowany asset został usunięty z magazynu
`packshot_not_approved`	422	nie	Sesja zdjęciowa nie ma zaakceptowanego packshotu dla produktu
`generation_failed`	502	tak	Błąd upstream providera AI
`internal_error`	500	tak	Nieoczekiwany błąd serwera

Kategorie niepowodzeń generowania

Błąd zgłoszony w trakcie wykonywania zadania niesie dodatkowo category, a jego code jest z tej kategorii wyprowadzony. Błędy walidacji, autoryzacji i limitów nigdy nie docierają do generatora, więc nie mają category.

`category`	`code`	`retryable`
`CONTENT_POLICY`	`content_policy_violation`	nie
`INPUT_MISSING`	`source_asset_unavailable`	nie
`INPUT_NOT_READY`	`source_asset_unavailable`	tak
`RATE_LIMIT`	`rate_limit_exceeded`	tak
`TRANSIENT_INFRA`	`generation_failed`	tak
`PROVIDER_CAPACITY`	`generation_failed`	tak
`INTERNAL_BUG`	`internal_error`	nie
`PROVIDER_ACCOUNT`	`internal_error`	nie

Zadania, które zawiodły przed wprowadzeniem tej klasyfikacji, raportują generation_failed bez category.

retryable przy niepowodzeniu generowania opisuje zadanie, nie żądanie: jest true tylko wtedy, gdy kolejna próba jest już zaplanowana. Kolumna powyżej to górny pułap dopuszczany przez daną kategorię, a zawęża go status samego zadania — gdy status jest końcowy (completed, failed, cancelled, expired), koperta raportuje false niezależnie od kategorii. Webhook job.failed wysyłany jest przy przejściu do stanu końcowego, więc jego error.retryable zawsze wynosi false.

Dwie konsekwencje warte uważnego przeczytania:

internal_error zgłoszony w trakcie generowania nigdy nie jest retryable, mimo że ten sam kod w odpowiedzi 500 byłby wart powtórzenia — zadanie nie zostanie za Ciebie ponowione, więc ponowne wysłanie go bez zmian nic nie da.
source_asset_unavailable figuruje w tabeli kodów powyżej jako nie-retryable i pozostaje to prawdą na poziomie żądania. Jako wynik zadania zależy to od kategorii: INPUT_MISSING wymaga czegoś, co możesz dostarczyć tylko Ty, i jest ostateczny, natomiast INPUT_NOT_READY oznacza, że sami wciąż przygotowujemy zasób — takie zadanie raportuje retryable: true, dopóki czeka, i false, gdy czas oczekiwania się wyczerpie i zadanie zakończy się jako failed.

Rozgałęziaj więc logikę na code i category, a retryable czytaj jako „czy zaplanowana jest kolejna próba”, nigdy jako „czy warto wysłać to ponownie”.

message_i18n nigdy nie zawiera tekstu od dostawcy ani wewnętrznej diagnostyki. Rozgałęziaj logikę na code, a message_i18n pokazuj człowiekowi.