Kódy chyb
Každá chybová odpověď má stejný tvar. docs_url vede na odpovídající položku na této stránce.
{ "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." }] } }}Odpovědi 429 navíc obsahují hlavičku Retry-After v sekundách. SDK tyto chyby vyhazují jako
typované podtřídy FrontmailError – viz Zpracování chyb.
bad_request HTTP 400
Význam: Požadavku nešlo porozumět (špatný content type, nečitelný JSON, nepodporovaná metoda).
Jak opravit: Posílejte Content-Type: application/json (u /v1/send-form multipart/form-data) a platné tělo. SDK to řeší za vás.
invalid_body HTTP 400
Význam: JSON je platný, ale neodpovídá schématu – třeba chybí template_id nebo má pole špatný typ. Seznam problémových polí je v details.
Jak opravit: Porovnejte tělo s referencí REST API a opravte pole uvedená v details.
invalid_idempotency_key HTTP 400
Význam: Hlavička Idempotency-Key je prázdná nebo delší než 255 znaků.
Jak opravit: Použijte UUID nebo jiný jedinečný řetězec do 255 znaků. SDK generují klíč pro každé logické odeslání samy.
unauthorized HTTP 401
Význam: Chybí klíč nebo ho nelze přiřadit k žádné organizaci.
Jak opravit: Pošlete public key jako user_id / X-Frontmail-Public-Key, nebo private key jako Authorization: Bearer sk_….
invalid_public_key HTTP 401
Význam: Public key neexistuje nebo byl rotován.
Jak opravit: Zkopírujte aktuální public key z Zabezpečení → Veřejný klíč v dashboardu. Po rotaci nasaďte web s novým klíčem.
invalid_private_key HTTP 401
Význam: Private key je neznámý nebo byl zneplatněn.
Jak opravit: Vytvořte nový private key v Zabezpečení → Privátní klíče a aktualizujte tajemství v prostředí serveru.
insufficient_credits HTTP 402
Význam: Organizace nemá kredity a zároveň používá režim reject. Ve výchozím režimu hold dostanete místo toho 202 se status: "held" – pokud už ovšem není plná fronta pozdržených zpráv (details.reason: "hold_queue_full", s held a limit).
Jak opravit: Kupte kreditový balíček, zapněte automatické dobíjení, přejděte na vyšší tarif nebo v Zabezpečení → Když dojdou kredity zvolte Pozdržet e-maily. U hold_queue_full navíc pozdržené zprávy uvolněte nebo zahoďte. Viz Hold fronta.
forbidden HTTP 403
Význam: Klíč nebo uživatel nemá na tuto akci oprávnění.
Jak opravit: Zkontrolujte roli člena týmu, případně pro serverové endpointy použijte private key.
origin_not_allowed HTTP 403
Význam: Požadavek přišel z Origin, který není v seznamu povolených domén – nebo nemá Origin/Referer vůbec (server, curl, nativní aplikace) a volba Povolit mobilní aplikace je vypnutá. V tom případě je details.reason no_origin.
Jak opravit: Přidejte doménu (např. example.com nebo *.example.com) v Zabezpečení → Povolené weby. Pro lokální vývoj přidejte i localhost. Pro nativní aplikace zapněte Povolit mobilní aplikace, na serveru místo public key použijte private key.
captcha_required HTTP 403
Význam: Šablona vyžaduje Turnstile, ale požadavek neobsahoval token.
Jak opravit: Vykreslete widget Turnstile (komponenty FrontmailForm pro React/Vue/Svelte to dělají samy) nebo pošlete turnstile_token. Volání ze serveru s private key tuto kontrolu přeskakují.
captcha_failed HTTP 403
Význam: Cloudflare token Turnstile odmítl – je neplatný, vypršel (platí zhruba 5 minut) nebo už byl použit. S details.reason: "hostname_mismatch" byl widget vyřešen na jiné doméně, než ze které požadavek přišel.
Jak opravit: Resetujte widget a nechte uživatele ověření zopakovat. Token nikdy nepoužívejte pro víc odeslání. U hostname_mismatch přidejte do svého widgetu Turnstile v Cloudflare všechny domény webu (např. example.com i www.example.com). Viz Turnstile.
captcha_not_configured HTTP 403
Význam: Šablona vyžaduje Turnstile, ale vaše organizace nemá vlastní klíče Turnstile, takže požadavky z webů nejde ověřit. V produkci se odmítají i testovací klíče Cloudflare (1x…, projdou vždy) – details.reason: "test_secret".
Jak opravit: Vytvořte si ve svém účtu Cloudflare bezplatný widget Turnstile a jeho site key a secret key vložte do Zabezpečení → Ochrana proti botům (Turnstile). Případně u šablony vypněte Vyžadovat CAPTCHA (Turnstile). Viz Turnstile.
headless_blocked HTTP 403
Význam: Je zapnuté blockHeadless a požadavek vypadá, že přišel z headless prohlížeče.
Jak opravit: U botů je to očekávané. Pokud se to týká skutečného uživatele, vypněte blockHeadless v inicializaci SDK nebo Blokovat headless prohlížeče v Zabezpečení → Ochrana proti zneužití.
recipient_blocked HTTP 403
Význam: Příjemce nebo sledovaná proměnná odpovídá položce na block listu.
Jak opravit: Pokud byla položka přidána omylem, odeberte ji v Zabezpečení → Seznam blokovaných hodnot.
private_key_required HTTP 403
Význam: Endpoint (batch, historie, šablony) nebo nastavení organizace vyžaduje private key.
Jak opravit: Volejte ho ze serveru s Authorization: Bearer sk_… – private key nikdy nedávejte do prohlížeče.
private_key_in_browser HTTP 403
Význam: Private key (Authorization: Bearer sk_… nebo accessToken) přišel s hlavičkou Origin, tedy z webové stránky, kde si ho může přečíst každý návštěvník. Private key patří jen na server.
Jak opravit: V prohlížeči používejte public key, private key nechte na serveru. Pokud ho v prohlížeči opravdu potřebujete (interní nástroj), zapněte v Zabezpečení volbu Povolit private key v prohlížeči – a pokud byl klíč někdy veřejný, vyměňte ho.
email_not_verified HTTP 403
Význam: Vlastník účtu zatím neověřil e-mailovou adresu. Neověřený účet může dashboard prohlížet, ale ne odesílat.
Jak opravit: Klikněte na odkaz v ověřovacím e-mailu, případně si ho nechte poslat znovu z banneru v dashboardu.
organization_suspended HTTP 403
Význam: Organizace byla pozastavena, obvykle kvůli zneužití nebo sporné platbě.
Jak opravit: Napište z adresy vlastníka na support@frontmail.dev.
plan_limit_reached HTTP 403
Význam: Narazili jste na limit tarifu mimo kredity – počet šablon, uživatelů nebo funkci, kterou váš tarif nemá. Vrací ho i šablony zmrazené po přechodu na nižší tarif – při odeslání i při Odeslat znovu v dashboardu (details.reason: "template_frozen").
Jak opravit: Přejděte na vyšší tarif – zmrazené šablony i členové se rozmrazí automaticky – nebo smažte šablony / zrušte nevyřízené pozvánky, abyste uvolnili místo. Viz Tarify a Změna tarifu.
dynamic_recipient_not_allowed HTTP 403
Význam: Pole příjemce (To/CC/BCC) se skládá z parametru, ale šablona dynamické příjemce nepovoluje. Chrání vás to před zneužitím jako otevřeného relay.
Jak opravit: Zapněte u šablony Povolit dynamického příjemce (Nastavení → Ochrana), jen pokud to opravdu potřebujete a máte zapnutý Turnstile a povolené domény.
dynamic_recipient_requires_captcha HTTP 403
Význam: Šablona bere příjemce z parametrů a požadavek používá veřejný klíč, ale šablona nevyžaduje CAPTCHA. Bez ní by kdokoli, kdo zkopíruje váš veřejný klíč, mohl šablonu poslat na libovolnou adresu.
Jak opravit: Přidejte klíče Cloudflare Turnstile v Zabezpečení → Ochrana proti botům a u šablony zapněte Vyžadovat CAPTCHA – nebo šablonu posílejte ze serveru privátním klíčem. Viz Povolené odkazy a zámek obsahu.
dynamic_field_not_allowed HTTP 403
Význam: Pole odesílatele se skládá z parametrů a požadavek používá veřejný klíč: adresa odesílatele nesmí nikdy, u šablon s dynamickým příjemcem ani jméno odesílatele a Reply-To. Seznam je v details.fields.
Jak opravit: Použijte v šabloně pevné hodnoty (adresa návštěvníka patří do Reply-To jen při pevném příjemci, třeba u kontaktního formuláře) – nebo posílejte ze serveru privátním klíčem.
link_not_allowed HTTP 403
Význam: Vykreslený e-mail odkazuje na doménu mimo povolené domény odkazů. Kontroluje se u odesílání veřejným klíčem do šablon s dynamickým příjemcem, u automatických odpovědí a u šablon s volbou Povolit jen odkazy na povolené domény. details.hosts obsahuje problémové domény (nikdy celou URL).
Jak opravit: Přidejte doménu v Zabezpečení → Povolené domény odkazů, napište odkaz přímo do šablony, nebo ho z parametrů odstraňte. Viz Povolené odkazy a zámek obsahu.
attachments_not_allowed HTTP 403
Význam: Požadavek obsahuje dynamické přílohy, ale šablona je nepovoluje, váš tarif přílohy nezahrnuje (Free), nebo je typ souboru blokovaný (spustitelné soubory, skripty, obrazy disků, HTML/SVG, Office s makry). POST /v1/uploads s public key navíc vyžaduje aspoň jednu šablonu, která přílohy povoluje.
Jak opravit: Zapněte u šablony Povolit přílohy z formuláře a ověřte, že váš tarif přílohy obsahuje.
not_found HTTP 404
Význam: URL neodpovídá žádnému endpointu.
Jak opravit: Zkontrolujte cestu a prefix /v1.
service_not_found HTTP 404
Význam: service_id v organizaci tohoto klíče neexistuje, nebo není nastavená výchozí služba.
Jak opravit: Zkopírujte ID z E-mailových služeb, případně označte jednu službu jako výchozí.
template_not_found HTTP 404
Význam: template_id v organizaci tohoto klíče neexistuje.
Jak opravit: Zkopírujte ID šablony ze Šablon. Klíče jiné organizace šablonu nevidí.
message_not_found HTTP 404
Význam: Zpráva neexistuje, je starší než retence historie, nebo nesedí status token.
Jak opravit: Použijte message_id a status_token z odpovědi na odeslání.
conflict HTTP 409
Význam: Prostředek se mezitím změnil nebo je ve stavu, který operaci nepovoluje (třeba uvolnění už odeslané zprávy). S details.reason: "subscription_not_active" byla odmítnuta změna tarifu, protože předplatné má nezaplacenou fakturu.
Jak opravit: Načtěte prostředek znovu a akci zopakujte. U subscription_not_active nejdřív zaplaťte otevřenou fakturu (Fakturace → Tarif → Karty a faktury) a pak tarif změňte.
idempotency_conflict HTTP 409
Význam: Stejný Idempotency-Key byl během 24 hodin použit s jiným tělem požadavku.
Jak opravit: Pro každé nové logické odeslání generujte nový klíč. Stejný klíč používejte jen při opakování identického požadavku.
payload_too_large HTTP 413
Význam: Tělo požadavku překračuje limit velikosti.
Jak opravit: Velké soubory posílejte přes uploady a parametry držte malé.
attachment_too_large HTTP 413
Význam: Celková velikost příloh v jednom požadavku překračuje limit tarifu.
Jak opravit: Soubory zkomprimujte, pošlete místo nich odkaz, nebo přejděte na vyšší tarif. Viz Tarify.
invalid_template_params HTTP 422
Význam: Parametry neodpovídají schématu šablony – chybí povinný parametr, hodnota má špatný typ nebo porušuje pravidlo (délka, rozsah, regex, výčet). Ve strict módu neprojdou ani neznámé parametry. Odesílání veřejným klíčem do šablon s dynamickým příjemcem navíc odmítá HTML parametry a hodnoty delší než 500 znaků (details.reason: "content_locked"). details obsahuje položku pro každé pole.
Jak opravit: Opravte pole z details. Typy vygenerované přes npx frontmail types tyto chyby odhalí už při kompilaci.
template_render_failed HTTP 422
Význam: Handlebars nedokázal šablonu s těmito parametry vykreslit (např. #each nad hodnotou, která není seznam, neznámý helper).
Jak opravit: Otevřete editor šablony – panel kontrol ukáže problém. Vyzkoušejte stejné parametry v náhledu.
invalid_recipient HTTP 422
Význam: Po vykreslení není hodnota To/CC/BCC/Reply-To platnou e-mailovou adresou, nebo je To prázdné.
Jak opravit: Zkontrolujte pole příjemců v šabloně a parametry, které používají.
sender_not_configured HTTP 422
Význam: E-mail nemá adresu odesílatele: šablona ji nemá a e-mailová služba nemá výchozího odesílatele (ani připojený účet či SMTP uživatelské jméno ve tvaru e-mailu). Vrací ho testovací odeslání z dashboardu.
Jak opravit: Nastavte Výchozí e-mail odesílatele v nastavení služby (E-mailové služby → služba) nebo e-mail odesílatele v nastavení šablony. U Amazon SES a většiny API musí jít o ověřenou identitu.
rate_limited HTTP 429
Význam: Příliš mnoho požadavků vzhledem k tarifu, IP adrese, klíči nebo nastavení limitRate – případně detekce anomálií organizaci zpomalila. details.scope: "recipient" znamená, že příjemce už dnes dostal maximum e-mailů s dynamickým příjemcem (Zabezpečení → E-mailů na příjemce za den); details.scope: "uploadbytes" znamená, že je vyčerpaný denní objem nahrávání přes public key.
Jak opravit: Počkejte Retry-After sekund (SDK to dělají samy). Pro hromadné odeslání použijte /v1/send-batch. Viz Rate limity.
test_send_limit HTTP 429
Význam: Vyčerpali jste dnešní bezplatná testovací odeslání z editoru šablon (20 denně).
Jak opravit: Počkejte do zítřka (UTC), nebo pošlete skutečnou zprávu přes API.
recipient_suppressed HTTP 451
Význam: Příjemce je na suppression listu kvůli trvalému odrazu, stížnosti nebo ručnímu zápisu. Kredit se nečerpá.
Jak opravit: Adresu odeberte z Blokovaných adres, jen pokud máte jistotu, že je platná a člověk o e-maily stojí.
internal_error HTTP 500
Význam: Něco selhalo na naší straně.
Jak opravit: Zopakujte požadavek se stejným Idempotency-Key (bezpečné, bez duplicit). Pokud problém trvá, podívejte se na status.frontmail.dev a kontaktujte podporu s ID požadavku.
provider_error HTTP 502
Význam: Poskytovatel e-mailu vrátil neočekávanou chybu při synchronní operaci, třeba při testu služby.
Jak opravit: Otevřete službu v dashboardu, uvidíte zprávu poskytovatele. Viz návody k poskytovatelům.
Chyby na straně klienta (SDK)
Tyto kódy vznikají přímo v SDK, bez odpovědi API. Chyba má status 0.
network_error SDK
Význam: Požadavek nedostal žádnou HTTP odpověď – zařízení je offline, selhalo DNS, blokuje ho rozšíření nebo pravidlo CORS/CSP. SDK už to zkoušelo znovu s backoffem.
Jak opravit: Zkontrolujte připojení a Content-Security-Policy (connect-src https://api.frontmail.dev). Požádejte uživatele o nový pokus.
timeout SDK
Význam: Pokus trval déle než timeoutMs (výchozí 15 s) a vypršely i všechny opakované pokusy.
Jak opravit: Opakování je bezpečné – SDK používá stejný idempotency klíč, takže nevznikne duplicita.
aborted SDK
Význam: Byl přerušen AbortSignal předaný v options.signal.
Jak opravit: Není co opravovat – komponenta se obvykle odmontovala nebo uživatel odešel ze stránky.
invalid_response SDK
Význam: Server odpověděl něčím, co není JSON odpověď Frontmailu – typicky proxy, captive portál nebo špatné apiUrl.
Jak opravit: Zkontrolujte volbu apiUrl a případnou proxy mezi klientem a api.frontmail.dev.
not_initialized SDK
Význam: send() bylo zavoláno před init() a bez klíče v parametrech volání.
Jak opravit: Zavolejte jednou při startu init({ publicKey }), nebo předejte klíč jako poslední argument.
private_key_in_browser SDK
Význam: Soukromý klíč (privateKey, v @frontmail/emailjs-compat accessToken) je nastavený v kódu, který běží ve webovém prohlížeči, nebo je @frontmail/node přibalené do stránky. Kdokoli na stránce by si klíč mohl zkopírovat a číst historii vašich zpráv.
Jak opravit: V prohlížeči používejte veřejný klíč (pk_…) a soukromý klíč nechte na serveru. Pokud se soukromý klíč někdy dostal na web, vyměňte ho. Jen pro interní nástroj na důvěryhodných počítačích můžete předat dangerouslyAllowPrivateKeyInBrowser: true.