Błędy API — co oznacza każdy kod i jak go naprawić

FastOG zwraca czytelne maszynowo kody błędów, gdy żądanie się nie powiedzie — renderowanie podpisanego obrazu OG lub wywołanie jednej z powierzchni administracyjnych dostępnych w produkcie. Każda odpowiedź z błędem zawiera:

• error — starszy krótki token. Nadal obecny przy każdym błędzie, aby starszy klient działał dalej.
• code — ten sam stabilny, udokumentowany kod błędu (tabela poniżej), pod nazwą używaną przez publiczne API.
• message — jednozdaniowy opis tego, co poszło nie tak.
• hint — krótki, prosty opis tego, co poszło nie tak i jak to naprawić.
• docs_url — link do tej strony, zakotwiczony w sekcji dla danego kodu.
• request_id — wiąże ten błąd HTTP z wierszem w tabeli Render Logs w dashboardzie (zwracany również w nagłówku odpowiedzi X-Request-ID). Powierzchnia, która nie ma nic do powiązania, odpowiada null, ale klucz jest zawsze obecny.

Powierzchnie dostępne w produkcie — panel administracyjny Shopify, WooCommerce Studio, mostek Wix i demo — odpowiadają tym samym envelope dla poniższych kodów, więc błąd oznacza to samo, gdziekolwiek go napotkasz. Powierzchnia modułu może zachować status HTTP, który zawsze zwracała dla danego kodu (na przykład render_failed odpowiada 503 przy eksporcie okładki i 502 w publicznym API); kod, komunikat, podpowiedź i link do dokumentacji się nie zmieniają.

Odczyt odpowiedzi z błędem

{
  "error": "invalid_signature",
  "code": "invalid_signature",
  "message": "The signature does not match.",
  "hint": "The signature did not match. Re-sign with your HMAC secret after every param change.",
  "request_id": "5f2a9c1e-..."
}

Jeśli otrzymasz odpowiedź, której nie rozumiesz, najszybsza droga to:

1. Zanotuj code.
2. Sprawdź swój builder URL — większość błędów to błędy podpisywania, a nie problemy z kontem.
3. Dopasuj kod poniżej, aby znaleźć dokładną przyczynę i poprawkę.
4. W dashboardzie otwórz Render Logs i filtruj po tym samym error_code — każdy wiersz pokazuje żądane parametry, więc możesz odtworzyć żądanie (i potwierdzić, że request_id się zgadza).

Podpisywanie i uwierzytelnianie

missing_signature

W Twoim żądaniu brakuje parametrów zapytania key i/lub s (sygnatura).

Poprawka: upewnij się, że Twój URL zawiera zarówno key=<api-key>, jak i s=<hmac-signature>. Użyj SDK lub przejdź przez przewodnik /docs/hmac-signature-guide, aby go zbudować.

invalid_signature

Wartość s nie zgadzała się z tym, co Twój sekret HMAC generuje dla tego URL-a.

Poprawka: sygnatura obejmuje każdy parametr zapytania oprócz s, z posortowanymi kluczami. Zmiana dowolnego parametru — w tym zmiana kolejności, różnice w kodowaniu URL lub dodanie białych znaków — unieważnia sygnaturę. Podpisuj ponownie po każdej zmianie. Upewnij się, że Twój sekret to ten sam, który został wyświetlony przy tworzeniu klucza API.

invalid_signature_format

Wartość s nie jest 64-znakowym ciągiem hex.

Poprawka: sygnatura musi być surowym hex SHA-256 (małe litery a-f0-9). Jeśli kodujesz wynik w base64 lub go obcinasz, użyj zwykłego hex.

expired_timestamp

Podany przez Ciebie znacznik czasu t jest starszy niż 5 minut.

Poprawka: generuj znacznik czasu od nowa za każdym razem, gdy budujesz URL. Ten kod dotyczy starszego przepływu z podpisanym URL-em; obecny przepływ HMAC v2 nie ma znacznika czasu.

invalid_api_key

Przekazany przez Ciebie key nie istnieje.

Poprawka: skopiuj pełny klucz API z dashboardu — to publiczny identyfikator zaczynający się od sk_. Jest publiczny i bezpieczny w URL-ach; to sekret (nigdy w URL-ach) dowodzi posiadania.

missing_hmac_secret

Klucz API nie ma skonfigurowanego sekretu HMAC.

Poprawka: utwórz nowy klucz API w dashboardzie — sekret HMAC jest generowany i wyświetlany jednorazowo przy tworzeniu.

Parametr / dane wejściowe

invalid_image_url

Właściwość zawierająca URL (image, brand_logo, logo, avatar, background_image, ...) nie jest publicznym adresem URL http(s).

Poprawka: przekaż publicznie dostępny adres URL https://.... Localhost, prywatne adresy IP i same ścieżki są odrzucane, aby zapobiec server-side request forgery.

Subskrypcja

subscription_required (402)

Żądanie trafiło do Dynamic API, ale Twoje konto nie ma aktywnego planu. Dostęp do API jest wyłącznie w ramach subskrypcji: plan jest warunkiem dostępu i oferuje ten sam zakres pokrycia i drabinkę możliwości, które sprzedają aplikacje FastOG. Same rendery nie są rozliczane — nie ma miesięcznego limitu renderów ani opłat za przekroczenie.

Poprawka: wybierz plan Dynamic API w panelu (dashboard) i utwórz klucz API. Odpowiedź zawiera top_up_url wskazujący na stronę z planami.

Usługa renderowania

store_blocked (403)

Renderowanie dla sklepu powiązanego z tym kluczem zostało wstrzymane przez FastOG (na przykład z powodu nadużyć lub niekontrolowanego użycia). Okładki już zapisane w pamięci podręcznej na edge mogą być nadal serwowane, dopóki nie wygasną. Skontaktuj się z pomocą techniczną, aby to rozwiązać; nic, co możesz zmienić w żądaniu, tego nie naprawi.

render_unreachable

Nie udało się połączyć z usługą renderowania (krótkie okno restartu).

Poprawka: ponów próbę za kilka sekund. Render nie został policzony dla tej próby.

render_failed

Usługa renderowania zwróciła błąd dla Twojego żądania.

Poprawka: zweryfikuj właściwości szablonu (template props) — zbyt długie/nieprawidłowo sformatowane wartości, nieobsługiwane pola lub nieosiągalny obraz źródłowy. Odpowiedź zawiera bazowy status. Render nie został policzony.

Powierzchnie administracyjne sklepu

Te kody odpowiadają z panelu administracyjnego Shopify i z WooCommerce Studio — osadzonych edytorów, w których pracuje sprzedawca, a nie z podpisanego API. Kilka z nich jest współdzielonych z publicznym API (invalid_image_url, render_failed, invalid_signature); te zachowują wpis udokumentowany powyżej.

Most Wix

Most Wix jest podpisywany przez aplikację Wix, a nie przez sesję sprzedawcy, więc jego błędy są adresowane do dewelopera aplikacji. Każda odpowiedź nadal zawiera code i request_id; identyfikator żądania mostu to ten z podpisanego envelope'a.

Powierzchnia demo

Demo to konsola sprzedażowa dostępna tylko dla właściciela, a nie endpoint dla sprzedawców.

Kody edytorów reguł z zakresem

Edytory reguł z zakresem (panel administracyjny Shopify i WooCommerce Studio) same tłumaczą te tokeny na język samego merchanta, więc ich odpowiedzi zawierają error i code, ale nie hint — drugi angielski opis tylko odbiegałby od zlokalizowanego, który merchant faktycznie widzi:

scope_already_defined, scoped_rule_limit_reached, scoped_rules_not_on_plan, scope_value_required, scope_value_too_long, unknown_scope_type, base_rule_required, scoped_rules_product_only, cannot_delete_base_rule.

Nadal masz problem?

• Otwórz stronę Render Logs w panelu — każde zdarzenie (sukces i odrzucenie) jest tam wymienione wraz z jego error_code, statusem HTTP i żądanymi parametrami.
• Uruchom php artisan og:diagnose na podpisanym URL, aby przejść przez cały potok i zobaczyć, na którym etapie występuje błąd.
• Sprawdź w pasku bocznym dokumentację dla frameworka, którego używasz (Next.js, Express, SvelteKit, ...).