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
`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. internal_error zgłoszony w trakcie generowania jest ostateczny, 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.

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