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 tylko do odczytu (gdy scope content.read będzie dostępny).

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