Rozwiązywanie problemów i odzyskiwanie

Każda sekcja poniżej zaczyna się od tego, co widzisz, wyjaśnia najczęstszą przyczynę i mówi, co zrobić. Pełne znaczenie każdego numeru błędu znajdziesz na stronie Błędy; ta strona odpowiada na pytanie „i co teraz?”.

Znajdź swój problem

Zbierz przydatne informacje

Zanim cokolwiek zmienisz, zapisz, co się stało. Każdy krok poniżej pójdzie wtedy szybciej, a właśnie tego potrzebuje wsparcie:

• Czas, najlepiej w UTC.
• Endpoint, który został wywołany, na przykład POST /api/v1/jobs/createTask.
• Status HTTP i code z treści odpowiedzi.
• request_id: znajdziesz go w treści odpowiedzi i w nagłówku odpowiedzi X-Request-Id.
• Identyfikator zadania, jeśli go masz. Zaczyna się od job_ i jest też widoczny na stronie Logi w konsoli.

Rozróżniaj trzy sytuacje, bo każda wymaga innego działania: API wprost odrzuciło żądanie (dostajesz błąd w formacie JSON – nic nie zostało utworzone ani pobrane), nie ma żadnej odpowiedzi (przekroczenie czasu albo zerwane połączenie – zadanie może istnieć; zobacz niżej) albo zadanie zostało przyjęte i później się nie powiodło (masz identyfikator zadania ze state: "failed").

Jeśli odpowiedź w ogóle nie jest w formacie JSON – na przykład to strona HTML albo zwykły tekst – pochodzi z naszej sieci brzegowej i nie dotarła do API. Zanotuj status HTTP i pierwsze linijki treści. Taka strona z kodem 403 zwykle oznacza, że żądanie pochodzi z regionu, którego nie możemy obsługiwać; ponowienie tego nie zmieni.

Nigdy nie umieszczaj kluczy API, haseł, pełnych promptów ani oryginalnych plików w ogólnych logach ani w zgłoszeniach do wsparcia.

Zapłacono, ale saldo się nie zmieniło

• Karta: saldo zmienia się dopiero wtedy, gdy dotrze do nas potwierdzenie od operatora płatności, zwykle w ciągu kilku sekund. Odśwież Rozliczenia i zajrzyj do sekcji Zlecenia doładowania.
• Kryptowaluty: środki trafiają na saldo, gdy sieć potwierdzi transakcję, zwykle po kilku minutach. Wpłata niższa niż pokazana kwota albo wysłana po wygaśnięciu strony płatności nie jest księgowana automatycznie.
• Przelew ręczny: otwórz zlecenie w sekcji Zlecenia doładowania i podaj numer referencyjny przelewu albo hash transakcji. Sprawdzamy go ręcznie, zwykle w ciągu kilku godzin.

Pełną listę przypadków znajdziesz w Przygotuj konto → Typowe problemy. Nadal brakuje środków? Rozpocznij rozmowę w sekcji Wsparcie (temat Rozliczenia), podając ID zlecenia, a przy kryptowalutach także hash transakcji. Nigdy nie wysyłaj numerów kart ani haseł.

Każde wywołanie zwraca 401 lub 403

Zacznij od wywołania, które jest bezpłatne i niczego nie zmienia – odczytu salda:

echo "${SPICY_API_KEY:0:9}"
curl https://api.spicyapi.ai/api/v1/chat/credit \
  -H "Authorization: Bearer $SPICY_API_KEY"

Pierwsza linijka powinna wypisać sk-spicy-. Jeśli nie wypisuje nic, klucz nie jest wczytany w tym terminalu – ustaw go ponownie (zobacz Przygotuj konto). Potem przeczytaj msg z odpowiedzi:

W żadnym z tych przypadków ponowienia nic nie zmienią.

Saldo, limity i wsparcie

• 40201 – dostępne saldo nie pokrywa szacowanej ceny zadania. Doładuj konto (zobacz Przygotuj konto), a potem wyślij to samo żądanie ponownie z tym samym Idempotency-Key. Przyznane środki promocyjne pokrywają tylko objęte nimi modele.
• 40202 – osiągnięto limit wydatków; msg mówi który. Limit klucza (This key has reached its …) podniesiesz w Klucze API → Edytuj albo odnowi się sam (dzienny o 00:00 UTC, miesięczny pierwszego dnia miesiąca, łączny nigdy). Limit zespołu (Workspace … budget has been reached) podnosi na stronie Zespół właściciel, administrator albo menedżer budżetu. Limitu platformy (Platform quota for today is exhausted…) nie da się podnieść; spróbuj ponownie po 00:00 UTC. Zobacz Limity wydatków.
• 429 – zbyt wiele żądań. Odczekaj tyle sekund, ile podaje Retry-After, i zwolnij tempo; najbardziej pomagają webhooki zamiast ciasnych pętli odpytywania. Jeśli komunikat brzmi Too many pending uploads…, czekanie nic nie da: dokończ już rozpoczęte przesyłanie plików. Zobacz Limity żądań.

Kontakt ze wsparciem: rozpocznij rozmowę w sekcji Wsparcie w konsoli albo napisz na support@spicyapi.ai. Dołącz informacje zebrane wyżej: czas, endpoint, code, request_id albo identyfikator zadania, czego oczekiwano i co się stało, a także strukturę żądania z usuniętymi prywatnymi wartościami. Nigdy nie wysyłaj klucza API.

Model niewidoczny lub niedostępny

• Modelu nie ma na twojej liście albo dostajesz 404: wywołaj GET /api/v1/models ze swoim kluczem API i użyj modelu, w którym zarówno enabled, jak i available mają wartość true, kopiując jego identyfikator co do znaku. Strona modelu w serwisie nie dowodzi, że twój klucz może go wywołać w tej chwili. Zobacz Modele.
• 50301 – model nie może teraz przyjmować zadań. Ponów kilka razy z coraz dłuższymi przerwami, a potem przestań; powtarzane żądania nie udostępnią niedostępnego modelu. Odśwież katalog i zapytaj osobę, która płaci, zanim przełączysz się na inny model.
• 40004 – model działa, ale nie z tym zestawem ustawień. msg podaje nazwę ustawienia w nawiasie. Zmień tę wartość (na przykład rozdzielczość albo proporcje obrazu), zamiast ponawiać.
• 40301 – model istnieje, ale ten klucz nie może z niego korzystać; zmień listę dozwolonych modeli klucza.

Nieprawidłowe dane wejściowe lub konflikt wyceny

• 400 – porównaj swoje input z aktualnym inputSchema modelu w katalogu: nazwy pól, typy, dozwolone wartości i wymagania warunkowe. Usuń pola, których model nie wymienia. Po zmianie modelu sprawdź to jeszcze raz, bo każdy model ma własny schemat.
• 40003 – przesłany plik nie zgadza się z tym, co zostało zadeklarowane przy prośbie o adres do przesyłania. Poproś o nowy adres do przesyłania z właściwym contentType i rozmiarem, a potem prześlij plik ponownie.
• 413 – treść żądania jest za duża. Przesyłaj media przez proces przesyłania, zamiast osadzać je w żądaniu.
• 40901 – wycena wygasła, żądanie zmieniło się po wycenie albo zmieniła się cena. Pobierz nową wycenę, pokaż nową kwotę osobie, która płaci, i potwierdź ponownie. Zobacz Wyceny.
• Inne 409 – obsłuż zależnie od operacji. Klucz użyty już z inną treścią żądania wymaga nowego, poprawnego Idempotency-Key dla nowego żądania, a nie niekończących się ponowień. Zobacz Błędy → Kiedy warto ponawiać po 409.

Przekroczenie czasu bez identyfikatora zadania

Przekroczenie czasu nie mówi, czy zadanie zostało utworzone. Nie wysyłaj żądania po prostu jeszcze raz z nowym kluczem – to może utworzyć drugie zadanie i drugą opłatę.

Przekroczenia czasu po stronie klienta, zamknięte karty przeglądarki i zerwane strumienie nie anulują przyjętego zadania, a przyjętego zadania nie da się anulować.

Zadanie się nie powiodło

Nieudane lub wygasłe zadania zwykle zwalniają całą blokadę. Niektóre odmowy dotyczące treści są płatne według zaakceptowanej wyceny, wyłącznie gdy strona modelu wyraźnie wskazuje ten wyjątek. Sprawdź settled i cost, aby poznać ostateczną kwotę.

• Nie ponawiaj bez zmian: invalid_request, unsupported_combination, content_rejected (wybrany model odrzucił treść – zmień prompt albo model).
• Warto ponowić po przerwie: rate_limited, upstream_unavailable, upstream_failed.
• Najpierw popraw: invalid_asset (prześlij plik ponownie), timeout (spróbuj krótszego czasu trwania albo niższej rozdzielczości), generation_failed (te same dane wejściowe zwykle kończą się tak samo).

errorMessage wyjaśnia przyczynę ludziom; może to być powód podany przez sam model, po angielsku. Logikę kodu rozgałęziaj wyłącznie po errorCode. Pełna tabela jest na stronie Błędy → Kody niepowodzenia zadań. Ponowienie to nowe zadanie, które – jeśli się powiedzie – zostanie rozliczone od nowa.

Zadanie utknęło w stanie queued lub running

Generacja wymaga czasu – długie wideo może powstawać kilka minut. Każde zadanie ma termin po stronie serwera, zwracany jako deadlineAt w recordInfo:

• Przed deadlineAt: dalej czekaj na callback albo odpytuj recordInfo z coraz dłuższymi przerwami (nie co sekundę).
• Po terminie: zadanie samo kończy się stanem expired z errorCode: "timeout", a jego blokada wraca w całości. Nie musisz niczego anulować – a przyjętych zadań i tak nie da się anulować.

Jeśli zadanie pozostaje w stanie running długo po swoim deadlineAt, skontaktuj się ze wsparciem i podaj identyfikator zadania.

Plik przesłany, ale dane wejściowe są odrzucane

• Pominięto zatwierdzenie. Udane wysłanie pliku metodą PUT nie wystarczy: wywołaj files/{fileId}/commit, a potem wpisz zwrócony adres spicy:// w pole wejściowe modelu. Nigdy nie przekazuj samego uploadUrl.
• Plik nie zgadza się z biletem. Sprawdź zadeklarowany Content-Type, rozmiar i format; niezgodność zwraca 40003.
• Plik wygasł. Przesłanego pliku można używać do chwili expiresAt z odpowiedzi na zatwierdzenie – domyślnie 1 dzień albo krócej, jeśli twoje konto usuwa przesłane pliki po zakończeniu zadania. Dlatego ponowienie zadania może wymagać ponownego przesłania pliku.
• Plik należy do innego konta. Adres spicy:// działa tylko z kluczami konta, które go przesłało.

Pełny proces przesyłania opisuje strona Media.

Brak callbacku lub wygasłe pobieranie

Callback nie dotarł:

1. Sprawdź, czy callBackUrl to adres https:// osiągalny z internetu. Zwykły http:// nie jest przyjmowany.
2. Sprawdź, czy twój odbiornik weryfikuje podpis na podstawie oryginalnych bajtów żądania, jeszcze przed parsowaniem JSON, i czy szybko odpowiada statusem 2xx. Powolna praca powinna trafiać do twojej własnej kolejki. Jeśli klucz podpisujący był niedawno wymieniany, odbiornik musi używać nowego: nie ma okresu przejściowego. Zobacz Webhooki.
3. Przejrzyj historię dostarczeń na stronie Webhooki w konsoli; możesz tam też ponowić dostarczenie.
4. W międzyczasie odczytuj zadanie przez recordInfo – odpytywanie zawsze jest poprawnym planem awaryjnym. Zobacz Webhooki.

Callbacki mogą przychodzić więcej niż raz albo z opóźnieniem, więc odfiltruj duplikaty, zanim zrealizujesz zamówienie.

Link do pobrania albo plik zniknął:

• Link do pobrania działa 20 minut. Jeśli wynik jest nadal przechowywany, po prostu poproś o nowy link; odświeżanie starego linku nie działa.
• Jeśli wynik jest jeszcze kopiowany do magazynu, odczekaj kilka sekund i zapytaj ponownie.
• Wyniki są przechowywane najwyżej około 14 dni, a krócej, jeśli twoje konto ma krótszy okres przechowywania. Gdy contentState ma wartość expired albo purged, pliku nie da się odzyskać – uruchom model ponownie. Zobacz Przechowywanie i usuwanie danych.

Strumień kończy się przedwcześnie

Zanim zaczniesz parsować strumień zgodnie ze swoim protokołem, sprawdź status HTTP i Content-Type. Fragmenty przychodzące z sieci nie są kompletnymi zdarzeniami, a zamknięte połączenie nie oznacza powodzenia: wypatruj zdarzenia końcowego protokołu, ewentualnego zdarzenia błędu i pilnuj własnego terminu w aplikacji. Nie zakładaj, że zerwany strumień był darmowy albo że można go wysłać ponownie bez kosztów – prawidłowe zużycie zarejestrowane przed rozłączeniem może zostać rozliczone. Zachowaj request_id i sprawdź swoje zapisy zużycia. Zobacz Tekst i streaming.

Uprawnienia w zespole

• Nie możesz utworzyć klucza. Przełącznik zakresu na górze lewego paska bocznego konsoli wskazuje zespół, w którym masz rolę Menedżer budżetu albo Tylko odczyt. Tworzenie kluczy wymaga roli Właściciel, Administrator albo Programista. Przełącz się na zakres Osobisty albo poproś administratora zespołu o rolę Programista.
• Widzisz zadanie, ale nie jego prompt ani wynik. Menedżerowie budżetu i członkowie z rolą Tylko odczyt widzą wyłącznie status, koszt i zużycie.
• Nie możesz przyjąć zaproszenia. Zaloguj się dokładnie tym adresem e-mail, na który wysłano zaproszenie. Zaproszenia wygasają po 7 dniach; jeśli twoje wygasło, poproś o nowe.
• Klucz zespołu zatrzymał się z kodem 40201. Klucze zespołu wydają saldo właściciela zespołu, więc to właściciel musi doładować konto.

Role i limity zespołu opisuje strona Konsola i zespoły.

Nie da się wystawić faktury

• Dane są niekompletne. Faktura wymaga nazwy (firmy albo twojego imienia i nazwiska), pierwszej linii adresu, miejscowości i kraju – wpisuje się je raz na górze sekcji Rozliczenia → Faktury.
• Znaku nie da się wydrukować. Na fakturze mogą się pojawić wyłącznie znaki alfabetu łacińskiego, greckiego i cyrylicy. Japońską albo koreańską nazwę firmy zapisz w jej zarejestrowanej formie w alfabecie łacińskim.
• Faktura już istnieje. Każde opłacone doładowanie i każdy zamknięty miesiąc można zafakturować jeden raz; pobierz istniejący dokument. Żeby poprawić dane, wybierz przy nim Wystaw ponownie.
• Miesiąc jest niedostępny. Zestawienie zużycia może dotyczyć tylko miesiąca, który już się skończył i w którym coś wydano.

Zobacz Rozliczenia → Faktury i zestawienia zużycia.

Powiązane strony

Błędy · Integracja produkcyjna · Idempotentność · Media · Webhooki · Tekst i streaming · Przygotuj konto