Kody błędów
Każda odpowiedź z błędem ma ten sam kształt. docs_url prowadzi do odpowiedniej pozycji na tej stronie.
{ "error": { "code": "invalid_template_params", "message": "Invalid template parameters. email: Invalid email address.", "docs_url": "https://docs.frontmail.dev/reference/errors/#invalid-template-params", "details": { "issues": [{ "param": "email", "code": "invalid_email", "message": "Invalid email address." }] } }}Odpowiedzi 429 zawierają dodatkowo nagłówek Retry-After z liczbą sekund. SDK zgłaszają te błędy
jako typowane podklasy FrontmailError – zobacz Obsługa błędów.
bad_request HTTP 400
Znaczenie: Nie udało się zrozumieć żądania (zły content type, nieczytelny JSON, nieobsługiwana metoda).
Jak naprawić: Wysyłaj Content-Type: application/json (albo multipart/form-data dla /v1/send-form) i prawidłową treść. SDK robią to za ciebie.
invalid_body HTTP 400
Znaczenie: JSON jest poprawny, ale nie pasuje do schematu – np. brakuje template_id albo pole ma zły typ. Listę błędnych pól znajdziesz w details.
Jak naprawić: Porównaj treść żądania z dokumentacją REST API i popraw pola wymienione w details.
invalid_idempotency_key HTTP 400
Znaczenie: Nagłówek Idempotency-Key jest pusty albo dłuższy niż 255 znaków.
Jak naprawić: Użyj UUID albo innego unikalnego ciągu o długości maksymalnie 255 znaków. SDK generują klucz dla każdej logicznej wysyłki.
unauthorized HTTP 401
Znaczenie: Nie podano klucza albo nie da się go przypisać do żadnej organizacji.
Jak naprawić: Przekaż klucz publiczny jako user_id / X-Frontmail-Public-Key albo klucz prywatny jako Authorization: Bearer sk_….
invalid_public_key HTTP 401
Znaczenie: Klucz publiczny nie istnieje albo został zmieniony (rotacja).
Jak naprawić: Skopiuj aktualny klucz publiczny z Bezpieczeństwo → Klucz publiczny w panelu. Po rotacji wdróż stronę z nowym kluczem.
invalid_private_key HTTP 401
Znaczenie: Klucz prywatny jest nieznany albo został unieważniony.
Jak naprawić: Utwórz nowy klucz prywatny w Bezpieczeństwo → Klucze prywatne i zaktualizuj sekret w środowisku serwera.
insufficient_credits HTTP 402
Znaczenie: Twoja organizacja nie ma już kredytów i używa trybu reject. W domyślnym trybie hold dostajesz zamiast tego 202 ze status: "held" – chyba że kolejka wstrzymanych wiadomości jest pełna (details.reason: "hold_queue_full", z polami held i limit).
Jak naprawić: Kup pakiet kredytów, włącz automatyczne doładowanie, przejdź na wyższy plan albo w Bezpieczeństwo → Gdy skończą się kredyty wybierz Wstrzymuj e-maile. Przy hold_queue_full dodatkowo zwolnij lub odrzuć wstrzymane wiadomości. Zobacz Kolejka wstrzymanych wiadomości.
forbidden HTTP 403
Znaczenie: Klucz lub użytkownik nie ma uprawnień do tej akcji.
Jak naprawić: Sprawdź rolę członka zespołu albo użyj klucza prywatnego dla endpointów serwerowych.
origin_not_allowed HTTP 403
Znaczenie: Żądanie przyszło z Origin, którego nie ma na liście dozwolonych domen – albo w ogóle nie ma Origin/Referer (serwer, curl, aplikacja natywna), a opcja Zezwól na aplikacje mobilne jest wyłączona. W tym przypadku details.reason to no_origin.
Jak naprawić: Dodaj domenę (np. example.com albo *.example.com) w Bezpieczeństwo → Dozwolone domeny. Do lokalnego developmentu potrzebny jest też localhost. Dla aplikacji natywnych włącz Zezwól na aplikacje mobilne; na serwerach używaj klucza prywatnego zamiast publicznego.
captcha_required HTTP 403
Znaczenie: Szablon wymaga Turnstile, a żądanie nie zawiera tokena.
Jak naprawić: Wyrenderuj widżet Turnstile (komponent FrontmailForm dla React/Vue/Svelte zrobi to za ciebie) albo przekaż turnstile_token. Wywołania z serwera kluczem prywatnym pomijają tę kontrolę.
captcha_failed HTTP 403
Znaczenie: Cloudflare odrzucił token Turnstile – jest nieprawidłowy, wygasł (tokeny żyją ok. 5 minut) albo został już użyty. Przy details.reason: "hostname_mismatch" widżet został rozwiązany na innej nazwie hosta niż ta, z której przyszło żądanie.
Jak naprawić: Zresetuj widżet i pozwól użytkownikowi rozwiązać go ponownie. Nigdy nie używaj tego samego tokena do kilku wysyłek. Przy hostname_mismatch dodaj do swojego widżetu Turnstile w Cloudflare wszystkie nazwy hostów strony (np. example.com i www.example.com). Zobacz Turnstile.
captcha_not_configured HTTP 403
Znaczenie: Szablon wymaga Turnstile, ale twoja organizacja nie dodała własnych kluczy Turnstile, więc żądań ze stron nie da się zweryfikować. Na produkcji odrzucane są też testowe klucze Cloudflare (1x…, zawsze przechodzą) (details.reason: "test_secret").
Jak naprawić: Utwórz darmowy widżet Turnstile na swoim koncie Cloudflare i dodaj jego klucz witryny oraz klucz tajny w Bezpieczeństwo → Ochrona przed botami (Turnstile). Albo wyłącz w szablonie Wymagaj CAPTCHA (Turnstile). Zobacz Turnstile.
headless_blocked HTTP 403
Znaczenie: Opcja blockHeadless jest włączona, a żądanie wygląda, jakby przyszło z przeglądarki headless.
Jak naprawić: W przypadku botów to oczekiwane zachowanie. Jeśli dotyczy to prawdziwego użytkownika, wyłącz blockHeadless w inicjalizacji SDK albo Blokuj przeglądarki headless w Bezpieczeństwo → Ochrona przed nadużyciami.
recipient_blocked HTTP 403
Znaczenie: Odbiorca lub sprawdzany parametr pasuje do wpisu na twojej liście blokad.
Jak naprawić: Usuń wpis z Bezpieczeństwo → Lista blokad, jeśli trafił tam przez pomyłkę.
private_key_required HTTP 403
Znaczenie: Endpoint (batch, historia, szablony) albo ustawienie organizacji wymaga klucza prywatnego.
Jak naprawić: Wywołuj go z serwera z nagłówkiem Authorization: Bearer sk_… – nigdy nie wysyłaj klucza prywatnego do przeglądarki.
private_key_in_browser HTTP 403
Znaczenie: Klucz prywatny (Authorization: Bearer sk_… albo accessToken) został wysłany z nagłówkiem Origin, czyli ze strony internetowej, gdzie każdy odwiedzający może go odczytać. Klucze prywatne to dane dostępowe wyłącznie dla serwerów.
Jak naprawić: W przeglądarce używaj klucza publicznego. Klucz prywatny trzymaj na serwerze. Jeśli naprawdę potrzebujesz go w przeglądarce (narzędzie wewnętrzne), włącz Zezwól na klucze prywatne w przeglądarkach w sekcji Bezpieczeństwo – i zmień klucz, jeśli kiedykolwiek był publiczny.
email_not_verified HTTP 403
Znaczenie: Właściciel konta nie potwierdził jeszcze adresu e-mail. Niepotwierdzone konta mogą przeglądać panel, ale nie mogą wysyłać.
Jak naprawić: Kliknij link w e-mailu weryfikacyjnym albo wyślij go ponownie z banera w panelu.
organization_suspended HTTP 403
Znaczenie: Organizacja została zawieszona, zwykle z powodu nadużyć lub spornej płatności.
Jak naprawić: Napisz na support@frontmail.dev z adresu właściciela.
plan_limit_reached HTTP 403
Znaczenie: Osiągnięto limit planu inny niż kredyty – liczbę szablonów, użytkowników albo funkcję spoza twojego planu. Ten błąd zwracają też elementy zamrożone po przejściu na niższy plan – przy wysyłce i przy Wyślij ponownie w panelu (details.reason: "template_frozen").
Jak naprawić: Przejdź na wyższy plan – zamrożone szablony i członkowie zostaną automatycznie odmrożeni – albo usuń szablony / cofnij oczekujące zaproszenia, żeby zrobić miejsce. Zobacz Plany i Zmiany planu.
dynamic_recipient_not_allowed HTTP 403
Znaczenie: Pole odbiorcy (Do/DW/UDW) jest budowane z parametru, ale szablon nie pozwala na dynamicznych odbiorców. To chroni cię przed wykorzystaniem jako otwarty przekaźnik (open relay).
Jak naprawić: Włącz Zezwól na dynamicznego odbiorcę w ustawieniach szablonu (Ustawienia → Ochrona) tylko wtedy, gdy naprawdę tego potrzebujesz i masz włączone Turnstile oraz dozwolone domeny.
dynamic_recipient_requires_captcha HTTP 403
Znaczenie: Szablon pobiera odbiorcę z parametrów, a żądanie używa klucza publicznego, ale szablon nie wymaga CAPTCHA. Bez tego każdy, kto skopiuje twój klucz publiczny, mógłby wysłać twój szablon na dowolny adres.
Jak naprawić: Dodaj swoje klucze Cloudflare Turnstile w Bezpieczeństwo → Ochrona przed botami i włącz w szablonie Wymagaj CAPTCHA – albo wysyłaj ten szablon z serwera kluczem prywatnym. Zobacz Dozwolone linki i blokada treści.
dynamic_field_not_allowed HTTP 403
Znaczenie: Pole nadawcy jest budowane z parametrów, a żądanie używa klucza publicznego: adres nadawcy (From) nigdy nie może pochodzić z parametrów, a w szablonach z dynamicznym odbiorcą także nazwa nadawcy i Reply-To. Listę pól znajdziesz w details.fields.
Jak naprawić: Użyj w szablonie stałych wartości (adres odwiedzającego pasuje do Reply-To tylko wtedy, gdy odbiorca jest stały, np. w formularzu kontaktowym) – albo wysyłaj z serwera kluczem prywatnym.
link_not_allowed HTTP 403
Znaczenie: Wyrenderowany e-mail zawiera link do domeny spoza listy dozwolonych domen linków. Sprawdzane przy wysyłkach kluczem publicznym do szablonów z dynamicznym odbiorcą, przy automatycznych odpowiedziach i w szablonach z opcją Zezwalaj tylko na linki do dozwolonych domen. details.hosts zawiera niedozwolone domeny (nigdy pełny URL).
Jak naprawić: Dodaj domenę w Bezpieczeństwo → Dozwolone domeny linków, wpisz link bezpośrednio w szablonie albo usuń go z parametrów. Zobacz Dozwolone linki i blokada treści.
attachments_not_allowed HTTP 403
Znaczenie: Żądanie zawiera dynamiczne załączniki, ale szablon na nie nie pozwala, twój plan nie obejmuje załączników (Free) albo typ pliku jest zablokowany (pliki wykonywalne, skrypty, obrazy dysków, HTML/SVG, pliki Office z makrami). POST /v1/uploads z kluczem publicznym wymaga też co najmniej jednego szablonu, który pozwala na załączniki.
Jak naprawić: Włącz Zezwól na załączniki z formularza w ustawieniach szablonu i upewnij się, że twój plan obejmuje załączniki.
not_found HTTP 404
Znaczenie: URL nie pasuje do żadnego endpointu.
Jak naprawić: Sprawdź ścieżkę i prefiks /v1.
service_not_found HTTP 404
Znaczenie: service_id nie istnieje w organizacji tego klucza albo nie ustawiono usługi domyślnej.
Jak naprawić: Skopiuj ID z Usługi e-mail albo oznacz jedną usługę jako domyślną.
template_not_found HTTP 404
Znaczenie: template_id nie istnieje w organizacji tego klucza.
Jak naprawić: Skopiuj ID szablonu z sekcji Szablony. Klucze z innej organizacji nie widzą tego szablonu.
message_not_found HTTP 404
Znaczenie: Wiadomość nie istnieje, jest starsza niż okres przechowywania historii albo token statusu się nie zgadza.
Jak naprawić: Użyj message_id i status_token z odpowiedzi na wysyłkę.
conflict HTTP 409
Znaczenie: Zasób został jednocześnie zmieniony albo jest w stanie, który nie pozwala na operację (np. zwolnienie wiadomości, która została już wysłana). Przy details.reason: "subscription_not_active" zmiana planu została odrzucona, bo subskrypcja ma nieopłaconą fakturę.
Jak naprawić: Wczytaj zasób ponownie i spróbuj jeszcze raz. Przy subscription_not_active opłać otwartą fakturę (Płatności → Plan → Zarządzaj kartami i fakturami), a potem zmień plan.
idempotency_conflict HTTP 409
Znaczenie: Ten sam Idempotency-Key został użyty w ciągu 24 godzin z inną treścią żądania.
Jak naprawić: Generuj nowy klucz dla każdej nowej logicznej wysyłki. Używaj ponownie tego samego klucza tylko przy powtarzaniu identycznego żądania.
payload_too_large HTTP 413
Znaczenie: Treść żądania przekracza limit rozmiaru.
Jak naprawić: Przenieś duże pliki do przesyłania plików i ogranicz rozmiar parametrów.
attachment_too_large HTTP 413
Znaczenie: Łączny rozmiar załączników w jednym żądaniu przekracza limit twojego planu.
Jak naprawić: Skompresuj pliki, wyślij zamiast nich link albo przejdź na wyższy plan. Zobacz Plany.
invalid_template_params HTTP 422
Znaczenie: Parametry nie pasują do schematu szablonu – brakuje wymaganego parametru, wartość ma zły typ albo łamie regułę (długość, zakres, wzorzec, lista wartości). W trybie ścisłym błąd powodują też nieznane parametry. Wysyłki kluczem publicznym do szablonów z dynamicznym odbiorcą dodatkowo odrzucają parametry HTML i wartości dłuższe niż 500 znaków (details.reason: "content_locked"). details zawiera jeden wpis na każde pole.
Jak naprawić: Popraw pola wymienione w details. Wygeneruj typy poleceniem npx frontmail types, żeby wyłapać to już podczas kompilacji.
translation_not_configured HTTP 422
Znaczenie: Zażądano tłumaczenia maszynowego, ale organizacja nie ma klucza API żadnego dostawcy tłumaczeń (albo tego wybranego).
Jak naprawić: Dodaj własny klucz OpenAI, Anthropic, Gemini lub DeepL w Ustawienia → Tłumaczenie maszynowe. Zobacz Tłumaczenia szablonów.
translation_invalid HTTP 422
Znaczenie: Dostawca zwrócił tłumaczenie, które zmieniło strukturę szablonu – brakuje wyrażenia Handlebars, linku lub adresu obrazka albo się różni. Nic nie zostało zapisane.
Jak naprawić: Spróbuj ponownie albo z innym dostawcą lub modelem, ewentualnie przetłumacz wariant ręcznie.
translation_provider_auth HTTP 422
Znaczenie: Dostawca tłumaczeń odrzucił klucz API organizacji (nieprawidłowy, wygasły albo bez dostępu do modelu).
Jak naprawić: Wymień klucz w Ustawienia → Tłumaczenie maszynowe albo wybierz model, do którego twoje konto ma dostęp.
template_render_failed HTTP 422
Znaczenie: Handlebars nie udało się wyrenderować szablonu z tymi parametrami (np. #each na czymś, co nie jest listą, albo nieznany helper).
Jak naprawić: Otwórz edytor szablonu – panel kontroli pokaże problem. Przetestuj w podglądzie z tymi samymi parametrami.
invalid_recipient HTTP 422
Znaczenie: Po wyrenderowaniu wartość Do/DW/UDW/Reply-To nie jest prawidłowym adresem e-mail albo pole Do jest puste.
Jak naprawić: Sprawdź pola odbiorców w szablonie i parametry, których używają.
sender_not_configured HTTP 422
Znaczenie: E-mail nie ma adresu nadawcy: szablon go nie ustawia, a usługa e-mail nie ma domyślnego nadawcy (ani podłączonego konta czy nazwy użytkownika SMTP w formie adresu e-mail). Zwracany przy wysyłkach testowych z panelu.
Jak naprawić: Ustaw Domyślny e-mail nadawcy w ustawieniach usługi (Usługi e-mail → usługa) albo e-mail nadawcy w ustawieniach szablonu. W Amazon SES i większości API adres musi być zweryfikowaną tożsamością.
rate_limited HTTP 429
Znaczenie: Za dużo żądań w stosunku do twojego planu, adresu IP, klucza lub ustawienia limitRate – albo wykrywanie anomalii spowolniło twoją organizację. details.scope: "recipient" oznacza, że odbiorca dostał już dzienne maksimum e-maili z dynamicznym odbiorcą (Bezpieczeństwo → E-maile na odbiorcę dziennie); details.scope: "uploadbytes" oznacza, że wyczerpano dzienny limit przesyłania plików kluczem publicznym.
Jak naprawić: Odczekaj Retry-After sekund (SDK robią to automatycznie). Do wysyłek zbiorczych używaj /v1/send-batch. Zobacz Rate limity.
test_send_limit HTTP 429
Znaczenie: Wykorzystano wszystkie dzisiejsze darmowe wysyłki testowe z edytora szablonów (20 dziennie).
Jak naprawić: Poczekaj do jutra (UTC) albo wyślij prawdziwą wiadomość przez API.
recipient_suppressed HTTP 451
Znaczenie: Odbiorca jest na twojej liście wykluczeń po trwałym odbiciu, zgłoszeniu spamu lub ręcznym dodaniu. Kredyt nie jest pobierany.
Jak naprawić: Usuń adres z Listy wykluczeń tylko wtedy, gdy masz pewność, że jest prawidłowy i ta osoba chce dostawać twoje e-maile.
internal_error HTTP 500
Znaczenie: Coś zawiodło po naszej stronie.
Jak naprawić: Powtórz żądanie z tym samym Idempotency-Key (bezpieczne, bez duplikatów). Jeśli problem się powtarza, sprawdź status.frontmail.dev i skontaktuj się z pomocą techniczną, podając ID żądania.
provider_error HTTP 502
Znaczenie: Dostawca poczty zwrócił nieoczekiwany błąd podczas operacji synchronicznej, np. testu usługi.
Jak naprawić: Otwórz usługę w panelu, żeby zobaczyć komunikat dostawcy. Zobacz poradniki dla dostawców.
translation_provider_error HTTP 502
Znaczenie: Dostawca tłumaczeń zwrócił błąd lub nie odpowiedział na czas. Status HTTP jest w details.status.
Jak naprawić: Spróbuj później. Najczęstszą przyczyną są limity lub przekroczony limit konta u dostawcy.
Błędy po stronie klienta (SDK)
Te kody generują same SDK, bez odpowiedzi API. Błąd ma status 0.
network_error SDK
Znaczenie: Żądanie nie dostało żadnej odpowiedzi HTTP – urządzenie jest offline, zawiódł DNS albo blokuje je rozszerzenie lub reguła CORS/CSP. SDK już ponawiało próby z backoffem.
Jak naprawić: Sprawdź połączenie i swoją Content-Security-Policy (connect-src https://api.frontmail.dev). Poproś użytkownika, żeby spróbował ponownie.
timeout SDK
Znaczenie: Próba trwała dłużej niż timeoutMs (domyślnie 15 s), a wszystkie ponowienia też przekroczyły limit czasu.
Jak naprawić: Ponowienie jest bezpieczne – SDK używa tego samego klucza idempotencji, więc duplikat nie zostanie wysłany.
aborted SDK
Znaczenie: AbortSignal przekazany w options.signal został przerwany.
Jak naprawić: Nie ma czego naprawiać – zwykle komponent został odmontowany albo użytkownik przeszedł na inną stronę.
invalid_response SDK
Znaczenie: Serwer odpowiedział czymś, co nie jest odpowiedzią JSON Frontmail – zwykle to proxy, captive portal albo zły apiUrl.
Jak naprawić: Sprawdź opcję apiUrl i ewentualne proxy między klientem a api.frontmail.dev.
not_initialized SDK
Znaczenie: send() zostało wywołane przed init() i bez klucza w opcjach wywołania.
Jak naprawić: Wywołaj init({ publicKey }) raz przy starcie albo przekaż klucz jako ostatni argument.
private_key_in_browser SDK
Znaczenie: Klucz prywatny (privateKey albo accessToken w @frontmail/emailjs-compat) został skonfigurowany w kodzie działającym w przeglądarce albo @frontmail/node trafił do bundla strony. Każdy odwiedzający stronę mógłby skopiować klucz i czytać twoją historię wiadomości.
Jak naprawić: W przeglądarce używaj klucza publicznego (pk_…), a klucz prywatny trzymaj na serwerze. Zmień klucz prywatny, jeśli kiedykolwiek trafił na stronę. Tylko dla narzędzia wewnętrznego na zaufanych komputerach przekaż dangerouslyAllowPrivateKeyInBrowser: true.