Kody błędów

Qamera AI API używa standardowych kodów statusu HTTP do wskazania wyniku każdego zapytania. Pomyślne zapytania zwracają 200. Odpowiedzi z błędem zawierają treść JSON z polem error opisującym problem.

Format odpowiedzi

Wszystkie odpowiedzi z błędem mają następującą strukturę:

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

Kody statusu

200 OK

Zapytanie zostało przetworzone pomyślnie. Treść odpowiedzi zawiera żądane dane lub potwierdzenie wykonanej akcji.

400 Bad Request

W treści zapytania brakuje wymaganych pól, zawiera nieprawidłowe wartości lub jest źle sformatowana.

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

Częste przyczyny:

• Brak wymaganych pól w treści POST.
• Nieprawidłowe typy pól (np. string zamiast oczekiwanej liczby).
• Źle sformatowany JSON.

401 Unauthorized

API key jest brakujący, nieprawidłowy, wygasły lub unieważniony.

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

Częste przyczyny:

• Brak nagłówka X-Api-Key lub Authorization.
• Klucz został unieważniony lub przekroczył datę wygaśnięcia.
• Błąd typograficzny w wartości klucza.

402 Payment Required

Konto powiązane z API key nie ma wystarczającej liczby kredytów do wykonania żądanej operacji.

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

Co zrobić:

• Dokup dodatkowe kredyty lub pakiet kredytów w ustawieniach rozliczeń workspace.
• Sprawdź bieżące saldo przed wysłaniem zapytań generowania.

403 Forbidden

API key nie posiada wymaganego scope dla tego endpointu.

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

Częste przyczyny:

• Klucz został wydany bez scope wymaganego dla żądanej akcji.
• Próba operacji POST kluczem, który ma wyłącznie scope content.read.

404 Not Found

Żądany zasób nie istnieje lub Twoje konto nie ma do niego dostępu.

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

Częste przyczyny:

• Nieprawidłowe ID zasobu w URL.
• Zasób należy do innego konta.
• Zasób został usunięty.

429 Too Many Requests

API key przekroczył limit zapytań wynoszący 60 na minutę.

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

Co zrobić:

• Odczekaj przed ponowieniem. Użyj exponential backoff z jitterem.
• Szczegółowe strategie ponawiania znajdziesz na stronie Rate Limiting.

500 Internal Server Error

Na serwerze wystąpił nieoczekiwany błąd.

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

Co zrobić:

• Ponów zapytanie po krótkim opóźnieniu.
• Jeśli błąd się powtarza, skontaktuj się z pomocą techniczną, podając szczegóły zapytania i przybliżony czas.

502 Bad Gateway

Zewnętrzny serwis, od którego zależy API, zwrócił nieoczekiwaną odpowiedź.

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

Częste przyczyny:

• Zewnętrzny serwis generowania AI jest tymczasowo niedostępny.
• Problemy sieciowe między Qamera AI a dostawcami usług.

Co zrobić:

• Ponów po kilku sekundach. Tego typu błędy są zwykle przejściowe.

503 Service Unavailable

Brak aktywnego generatora treści do obsłużenia zapytania.

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

Częste przyczyny:

• Wszystkie workery generowania są offline lub w trakcie konserwacji.
• Tymczasowe problemy z wydajnością w godzinach szczytu.

Co zrobić:

• Ponów po 30–60 sekundach.
• Sprawdź stronę statusu Qamera AI pod kątem bieżących incydentów.

Tabela podsumowująca

Kategorie niepowodzeń zadań

Kody powyżej mówią, czy powiodło się Twoje zapytanie. Zadanie generowania to co innego: jego zlecenie kończy się natychmiast kodem 200, a właściwa praca dzieje się później. Zadanie, które zawiedzie w trakcie, jest raportowane wewnątrz udanej odpowiedzi, a nie jako błąd HTTP.

Gdy odpytujesz GET /api/external/orders/:id, każde zadanie niesie dwa pola opisujące niepowodzenie:

• errorCategory — ustalona wartość z tabeli poniżej. Na tym opieraj logikę.
• errorHint — jedno zdanie wyjaśniające kategorię i co z nią zrobić. Pokaż je człowiekowi, nie parsuj.

Oba są null dla zadań zakończonych powodzeniem oraz dla niepowodzeń zapisanych, zanim ta klasyfikacja powstała.

Pierwsze trzy są ponawiane automatycznie, więc zadanie z taką kategorią może mimo wszystko zakończyć się powodzeniem — traktuj je jako informację o postępie, nie jako wynik końcowy. Działaj dopiero, gdy zamówienie przestanie się zmieniać, a status zadania to failed.

Surowe komunikaty od dostawców świadomie nie są udostępniane. Zawierają nazwy dostawców i szczegóły wewnętrznych systemów, które zmieniają się bez zapowiedzi — integracje, które je parsowały, psuły się przy każdej zmianie dostawcy. Stabilnym kontraktem jest kategoria.