Kódy chýb
Každá chybová odpoveď má rovnaký tvar. docs_url vedie na zodpovedajúcu položku na tejto stránke.
{ "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." }] } }}Odpovede 429 navyše obsahujú hlavičku Retry-After v sekundách. SDK tieto chyby vyhadzujú ako
typované podtriedy FrontmailError – pozrite Spracovanie chýb.
bad_request HTTP 400
Význam: Požiadavke sa nedalo porozumieť (nesprávny content type, nečitateľný JSON, nepodporovaná metóda).
Ako to opraviť: Posielajte Content-Type: application/json (pri /v1/send-form multipart/form-data) a platné telo. SDK to robia za vás.
invalid_body HTTP 400
Význam: JSON je platný, ale nezodpovedá schéme – napríklad chýba template_id alebo má pole nesprávny typ. Zoznam problémových polí je v details.
Ako to opraviť: Porovnajte telo s referenciou REST API a opravte polia uvedené v details.
invalid_idempotency_key HTTP 400
Význam: Hlavička Idempotency-Key je prázdna alebo dlhšia ako 255 znakov.
Ako to opraviť: Použite UUID alebo iný jedinečný reťazec s najviac 255 znakmi. SDK generujú kľúč pre každé logické odoslanie samy.
unauthorized HTTP 401
Význam: Chýba kľúč alebo ho nemožno priradiť k žiadnej organizácii.
Ako to opraviť: Pošlite verejný kľúč ako user_id / X-Frontmail-Public-Key, alebo súkromný kľúč ako Authorization: Bearer sk_….
invalid_public_key HTTP 401
Význam: Verejný kľúč neexistuje alebo bol vymenený.
Ako to opraviť: Skopírujte aktuálny verejný kľúč z Zabezpečenie → Verejný kľúč v dashboarde. Po výmene nasaďte web s novým kľúčom.
invalid_private_key HTTP 401
Význam: Súkromný kľúč je neznámy alebo bol zneplatnený.
Ako to opraviť: Vytvorte nový súkromný kľúč v Zabezpečenie → Súkromné kľúče a aktualizujte tajný údaj v prostredí servera.
insufficient_credits HTTP 402
Význam: Vaša organizácia nemá žiadne kredity a zároveň používa režim reject. V predvolenom režime hold namiesto toho dostanete 202 so status: "held" – ak už nie je plná fronta pozdržaných e-mailov (details.reason: "hold_queue_full", s held a limit).
Ako to opraviť: Kúpte kreditový balík, zapnite automatické dobíjanie, prejdite na vyšší tarif alebo v Zabezpečenie → Keď vám dôjdu kredity zvoľte Pozdržať e-maily. Pri hold_queue_full navyše pozdržané e-maily uvoľnite alebo zahoďte. Pozri Fronta pozdržaných e-mailov.
forbidden HTTP 403
Význam: Kľúč alebo používateľ nemá na túto akciu oprávnenie.
Ako to opraviť: Skontrolujte rolu člena tímu, prípadne pre serverové endpointy použite súkromný kľúč.
origin_not_allowed HTTP 403
Význam: Požiadavka prišla z Origin, ktorý nie je v zozname povolených domén – alebo nemá Origin/Referer vôbec (server, curl, natívna aplikácia) a voľba Povoliť mobilné aplikácie je vypnutá. V tom prípade je details.reason no_origin.
Ako to opraviť: Pridajte doménu (napr. example.com alebo *.example.com) v Zabezpečenie → Povolené weby. Pre lokálny vývoj pridajte aj localhost. Pre natívne aplikácie zapnite Povoliť mobilné aplikácie, na serveri namiesto verejného kľúča použite súkromný.
captcha_required HTTP 403
Význam: Šablóna vyžaduje Turnstile, ale požiadavka neobsahovala token.
Ako to opraviť: Vykreslite widget Turnstile (komponenty FrontmailForm pre React/Vue/Svelte to urobia za vás) alebo pošlite turnstile_token. Volania zo servera so súkromným kľúčom túto kontrolu preskakujú.
captcha_failed HTTP 403
Význam: Cloudflare token Turnstile odmietol – je neplatný, vypršal (platí asi 5 minút) alebo už bol použitý. So details.reason: "hostname_mismatch" bol widget vyriešený na inej doméne, než z ktorej prišla požiadavka.
Ako to opraviť: Resetujte widget a nechajte používateľa overenie zopakovať. Token nikdy nepoužívajte na viac odoslaní. Pri hostname_mismatch pridajte do svojho widgetu Turnstile v Cloudflare všetky domény webu (napr. example.com aj www.example.com). Pozri Turnstile.
captcha_not_configured HTTP 403
Význam: Šablóna vyžaduje Turnstile, ale vaša organizácia nemá vlastné kľúče Turnstile, takže požiadavky z webov nemožno overiť. V produkcii sa odmietajú aj testovacie kľúče Cloudflare (1x…, prejdú vždy) – details.reason: "test_secret".
Ako to opraviť: Vytvorte si vo svojom účte Cloudflare bezplatný widget Turnstile a jeho site key a secret key vložte do Zabezpečenie → Ochrana pred botmi (Turnstile). Prípadne pri šablóne vypnite Vyžadovať CAPTCHA (Turnstile). Pozri Turnstile.
headless_blocked HTTP 403
Význam: Je zapnuté blockHeadless a požiadavka vyzerá, že prišla z headless prehliadača.
Ako to opraviť: Pri botoch je to očakávané. Ak sa to týka skutočného používateľa, vypnite blockHeadless v inicializácii SDK alebo Blokovať headless prehliadače v Zabezpečenie → Ochrana pred zneužitím.
recipient_blocked HTTP 403
Význam: Príjemca alebo sledovaný parameter zodpovedá položke na vašom zozname blokovaných hodnôt.
Ako to opraviť: Ak bola položka pridaná omylom, odstráňte ju v Zabezpečenie → Zoznam blokovaných hodnôt.
private_key_required HTTP 403
Význam: Endpoint (batch, história, šablóny) alebo nastavenie organizácie vyžaduje súkromný kľúč.
Ako to opraviť: Volajte ho zo servera s Authorization: Bearer sk_… – súkromný kľúč nikdy nedávajte do prehliadača.
private_key_in_browser HTTP 403
Význam: Súkromný kľúč (Authorization: Bearer sk_… alebo accessToken) prišiel s hlavičkou Origin, teda z webovej stránky, kde si ho môže prečítať každý návštevník. Súkromné kľúče patria len na server.
Ako to opraviť: V prehliadači používajte verejný kľúč, súkromný nechajte na serveri. Ak ho v prehliadači naozaj potrebujete (interný nástroj), zapnite v Zabezpečenie voľbu Povoliť súkromné kľúče v prehliadačoch – a ak bol kľúč niekedy verejný, vymeňte ho.
email_not_verified HTTP 403
Význam: Vlastník účtu ešte neoveril svoju e-mailovú adresu. Neoverený účet si môže dashboard prezerať, ale nemôže odosielať.
Ako to opraviť: Kliknite na odkaz v overovacom e-maile, prípadne si ho dajte poslať znova z bannera v dashboarde.
organization_suspended HTTP 403
Význam: Organizácia bola pozastavená, zvyčajne pre zneužitie alebo spornú platbu.
Ako to opraviť: Napíšte z adresy vlastníka na support@frontmail.dev.
plan_limit_reached HTTP 403
Význam: Dosiahli ste limit tarifu iný ako kredity – počet šablón, používateľov alebo funkciu, ktorú váš tarif nemá. Vracajú ho aj položky zmrazené po prechode na nižší tarif – pri odoslaní aj pri Odoslať znova v dashboarde (details.reason: "template_frozen").
Ako to opraviť: Prejdite na vyšší tarif – zmrazené šablóny aj členovia sa rozmrazia automaticky – alebo vymažte šablóny / zrušte nevybavené pozvánky, aby ste uvoľnili miesto. Pozri Tarify a Zmena tarifu.
dynamic_recipient_not_allowed HTTP 403
Význam: Pole príjemcu (To/CC/BCC) sa skladá z parametra, ale šablóna dynamických príjemcov nepovoľuje. Chráni vás to pred zneužitím ako otvoreného relay.
Ako to opraviť: Zapnite pri šablóne Povoliť dynamického príjemcu (Nastavenia → Ochrana), len ak to naozaj potrebujete a máte zapnutý Turnstile a povolené domény.
dynamic_recipient_requires_captcha HTTP 403
Význam: Šablóna berie príjemcu z parametrov a požiadavka používa verejný kľúč, ale šablóna nevyžaduje CAPTCHA. Bez nej by ktokoľvek, kto skopíruje váš verejný kľúč, mohol vašu šablónu poslať na ľubovoľnú adresu.
Ako to opraviť: Pridajte svoje kľúče Cloudflare Turnstile v Zabezpečenie → Ochrana pred botmi a pri šablóne zapnite Vyžadovať CAPTCHA – alebo túto šablónu posielajte zo servera súkromným kľúčom. Pozri Povolené odkazy a zámok obsahu.
dynamic_field_not_allowed HTTP 403
Význam: Pole odosielateľa sa skladá z parametrov a požiadavka používa verejný kľúč: adresa odosielateľa nesmie nikdy, pri šablónach s dynamickým príjemcom ani meno odosielateľa a Reply-To. Zoznam je v details.fields.
Ako to opraviť: Použite v šablóne pevné hodnoty (adresa návštevníka patrí do Reply-To len pri pevnom príjemcovi, napríklad pri kontaktnom formulári) – alebo posielajte zo servera súkromným kľúčom.
link_not_allowed HTTP 403
Význam: Vykreslený e-mail odkazuje na doménu mimo povolených domén odkazov. Kontroluje sa pri odosielaní verejným kľúčom do šablón s dynamickým príjemcom, pri automatických odpovediach a pri šablónach s voľbou Povoliť len odkazy na povolené domény. details.hosts obsahuje problémové domény (nikdy celú URL).
Ako to opraviť: Pridajte doménu v Zabezpečenie → Povolené domény odkazov, napíšte odkaz priamo do šablóny alebo ho z parametrov odstráňte. Pozri Povolené odkazy a zámok obsahu.
attachments_not_allowed HTTP 403
Význam: Požiadavka obsahuje dynamické prílohy, ale šablóna ich nepovoľuje, váš tarif prílohy nezahŕňa (Free) alebo je typ súboru blokovaný (spustiteľné súbory, skripty, obrazy diskov, HTML/SVG, súbory Office s makrami). POST /v1/uploads s verejným kľúčom navyše vyžaduje aspoň jednu šablónu, ktorá prílohy povoľuje.
Ako to opraviť: Zapnite pri šablóne Povoliť prílohy z formulára a overte, že váš tarif prílohy obsahuje.
not_found HTTP 404
Význam: URL nezodpovedá žiadnemu endpointu.
Ako to opraviť: Skontrolujte cestu a prefix /v1.
service_not_found HTTP 404
Význam: service_id v organizácii tohto kľúča neexistuje alebo nie je nastavená predvolená služba.
Ako to opraviť: Skopírujte ID z E-mailových služieb, prípadne označte jednu službu ako predvolenú.
template_not_found HTTP 404
Význam: template_id v organizácii tohto kľúča neexistuje.
Ako to opraviť: Skopírujte ID šablóny zo Šablón. Kľúče inej organizácie šablónu nevidia.
message_not_found HTTP 404
Význam: Správa neexistuje, je staršia ako doba uchovávania histórie alebo nesedí status token.
Ako to opraviť: Použite message_id a status_token z odpovede na odoslanie.
conflict HTTP 409
Význam: Zdroj sa medzitým zmenil alebo je v stave, ktorý operáciu nepovoľuje (napr. uvoľnenie už odoslanej správy). So details.reason: "subscription_not_active" bola zmena tarifu odmietnutá, pretože predplatné má nezaplatenú faktúru.
Ako to opraviť: Znova načítajte zdroj a akciu zopakujte. Pri subscription_not_active najprv zaplaťte otvorenú faktúru (Fakturácia → Tarif → Spravovať karty a faktúry) a potom tarif zmeňte.
idempotency_conflict HTTP 409
Význam: Rovnaký Idempotency-Key bol počas 24 hodín použitý s iným telom požiadavky.
Ako to opraviť: Pre každé nové logické odoslanie vygenerujte nový kľúč. Rovnaký kľúč použite len pri opakovaní identickej požiadavky.
payload_too_large HTTP 413
Význam: Telo požiadavky prekračuje limit veľkosti.
Ako to opraviť: Veľké súbory posielajte cez nahrávanie súborov a parametre udržujte malé.
attachment_too_large HTTP 413
Význam: Celková veľkosť príloh v jednej požiadavke prekračuje limit vášho tarifu.
Ako to opraviť: Súbory skomprimujte, pošlite namiesto nich odkaz alebo prejdite na vyšší tarif. Pozri Tarify.
invalid_template_params HTTP 422
Význam: Parametre nezodpovedajú schéme šablóny – chýba povinný parameter, hodnota má nesprávny typ alebo porušuje pravidlo (dĺžka, rozsah, vzor, výber). V prísnom režime neprejdú ani neznáme parametre. Odosielanie verejným kľúčom do šablón s dynamickým príjemcom navyše odmieta HTML parametre a hodnoty dlhšie ako 500 znakov (details.reason: "content_locked"). details obsahuje položku pre každé pole.
Ako to opraviť: Opravte polia uvedené v details. Typy vygenerované cez npx frontmail types tieto chyby odhalia už pri kompilácii.
translation_not_configured HTTP 422
Význam: Bol požadovaný strojový preklad, ale organizácia nemá API kľúč žiadneho poskytovateľa prekladov (alebo toho požadovaného).
Ako to opraviť: Pridajte vlastný kľúč OpenAI, Anthropic, Gemini alebo DeepL v Nastavenia → Strojový preklad. Pozrite Preklady šablón.
translation_invalid HTTP 422
Význam: Poskytovateľ vrátil preklad, ktorý zmenil štruktúru šablóny – chýba alebo sa líši výraz Handlebars, odkaz či adresa obrázka. Nič sa neuložilo.
Ako to opraviť: Skúste to znova alebo s iným poskytovateľom či modelom, prípadne variant preložte ručne.
translation_provider_auth HTTP 422
Význam: Poskytovateľ prekladov odmietol API kľúč organizácie (neplatný, expirovaný alebo bez prístupu k modelu).
Ako to opraviť: Vymeňte kľúč v Nastavenia → Strojový preklad alebo zvoľte model, ku ktorému má váš účet prístup.
template_render_failed HTTP 422
Význam: Handlebars nedokázal šablónu s týmito parametrami vykresliť (napr. #each nad hodnotou, ktorá nie je zoznam, neznámy helper).
Ako to opraviť: Otvorte editor šablóny – panel kontrol ukáže problém. Vyskúšajte rovnaké parametre v náhľade.
invalid_recipient HTTP 422
Význam: Po vykreslení nie je hodnota To/CC/BCC/Reply-To platnou e-mailovou adresou alebo je To prázdne.
Ako to opraviť: Skontrolujte polia príjemcov v šablóne a parametre, ktoré používajú.
sender_not_configured HTTP 422
Význam: E-mail nemá adresu odosielateľa: šablóna ju nemá a e-mailová služba nemá predvoleného odosielateľa (ani pripojený účet či SMTP používateľské meno v tvare e-mailu). Vracia ho testovacie odoslanie z dashboardu.
Ako to opraviť: Nastavte Predvolený e-mail odosielateľa v nastaveniach služby (E-mailové služby → služba) alebo e-mail odosielateľa v nastaveniach šablóny. Pri Amazon SES a väčšine API musí ísť o overenú identitu.
rate_limited HTTP 429
Význam: Príliš veľa požiadaviek vzhľadom na tarif, IP adresu, kľúč alebo nastavenie limitRate – prípadne detekcia anomálií vašu organizáciu spomalila. details.scope: "recipient" znamená, že príjemca už dnes dostal maximum e-mailov s dynamickým príjemcom (Zabezpečenie → E-mailov na príjemcu za deň); details.scope: "uploadbytes" znamená, že je vyčerpaný denný objem nahrávania s verejným kľúčom.
Ako to opraviť: Počkajte Retry-After sekúnd (SDK to robia automaticky). Na hromadné odosielanie použite /v1/send-batch. Pozri Rate limity.
test_send_limit HTTP 429
Význam: Vyčerpali ste dnešné bezplatné testovacie odoslania z editora šablón (20 denne).
Ako to opraviť: Počkajte do zajtra (UTC) alebo pošlite skutočnú správu cez API.
recipient_suppressed HTTP 451
Význam: Príjemca je na zozname blokovaných adries pre trvalé nedoručenie, sťažnosť alebo ručný zápis. Kredit sa nečerpá.
Ako to opraviť: Adresu odstráňte z Blokovaných adries, len ak ste si istí, že je platná a človek o vaše e-maily stojí.
internal_error HTTP 500
Význam: Niečo zlyhalo na našej strane.
Ako to opraviť: Zopakujte požiadavku s rovnakým Idempotency-Key (bezpečné, bez duplikátov). Ak problém pretrváva, pozrite si status.frontmail.dev a kontaktujte podporu s ID požiadavky.
provider_error HTTP 502
Význam: Poskytovateľ e-mailov vrátil neočakávanú chybu pri synchrónnej operácii, napríklad pri teste služby.
Ako to opraviť: Otvorte službu v dashboarde, uvidíte správu od poskytovateľa. Pozri návody k poskytovateľom.
translation_provider_error HTTP 502
Význam: Poskytovateľ prekladov zlyhal alebo neodpovedal včas. HTTP status je v details.status.
Ako to opraviť: Skúste to neskôr. Najčastejšou príčinou sú limity alebo kvóta vášho účtu u poskytovateľa.
Chyby na strane klienta (SDK)
Tieto kódy vznikajú priamo v SDK, bez odpovede API. Chyba má status 0.
network_error SDK
Význam: Požiadavka nedostala žiadnu HTTP odpoveď – zariadenie je offline, zlyhalo DNS, blokuje ju rozšírenie alebo pravidlo CORS/CSP. SDK to už skúšalo znova s backoffom.
Ako to opraviť: Skontrolujte pripojenie a Content-Security-Policy (connect-src https://api.frontmail.dev). Požiadajte používateľa, aby to skúsil znova.
timeout SDK
Význam: Pokus trval dlhšie ako timeoutMs (predvolene 15 s) a vypršali aj všetky opakované pokusy.
Ako to opraviť: Opakovanie je bezpečné – SDK používa rovnaký idempotenčný kľúč, takže nevznikne duplikát.
aborted SDK
Význam: AbortSignal odovzdaný v options.signal bol prerušený.
Ako to opraviť: Nie je čo opravovať – komponent sa zvyčajne odmontoval alebo používateľ odišiel zo stránky.
invalid_response SDK
Význam: Server odpovedal niečím, čo nie je JSON odpoveď Frontmailu – typicky proxy, captive portál alebo nesprávne apiUrl.
Ako to opraviť: Skontrolujte voľbu apiUrl a prípadnú proxy medzi klientom a api.frontmail.dev.
not_initialized SDK
Význam: send() bolo zavolané pred init() a bez kľúča v parametroch volania.
Ako to opraviť: Zavolajte raz pri štarte init({ publicKey }) alebo odovzdajte kľúč ako posledný argument.
private_key_in_browser SDK
Význam: Súkromný kľúč (privateKey, v @frontmail/emailjs-compat accessToken) je nastavený v kóde, ktorý beží vo webovom prehliadači, alebo je @frontmail/node pribalené do stránky. Ktokoľvek na stránke by si mohol kľúč skopírovať a čítať históriu vašich správ.
Ako to opraviť: V prehliadači používajte verejný kľúč (pk_…) a súkromný kľúč nechajte na serveri. Ak sa súkromný kľúč niekedy dostal na web, vymeňte ho. Len pre interný nástroj na dôveryhodných počítačoch môžete odovzdať dangerouslyAllowPrivateKeyInBrowser: true.