Fehlercodes
Jede Fehlerantwort hat dieselbe Form. docs_url verweist auf den passenden Eintrag auf dieser Seite.
{ "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." }] } }}Antworten mit 429 enthalten zusätzlich den Header Retry-After in Sekunden. Die SDKs werfen diese
Fehler als typisierte Unterklassen von FrontmailError – siehe
Fehlerbehandlung.
bad_request HTTP 400
Bedeutung: Die Anfrage war nicht verständlich (falscher Content-Type, nicht lesbares JSON, nicht unterstützte Methode).
Lösung: Senden Sie Content-Type: application/json (bzw. multipart/form-data für /v1/send-form) und einen gültigen Body. Die SDKs erledigen das für Sie.
invalid_body HTTP 400
Bedeutung: Der JSON-Body ist gültig, entspricht aber nicht dem Schema – z. B. fehlt template_id oder ein Feld hat den falschen Typ. details listet die fehlerhaften Felder auf.
Lösung: Vergleichen Sie den Body mit der REST-API-Referenz und korrigieren Sie die in details genannten Felder.
invalid_idempotency_key HTTP 400
Bedeutung: Der Header Idempotency-Key ist leer oder länger als 255 Zeichen.
Lösung: Verwenden Sie eine UUID oder eine andere eindeutige Zeichenkette mit höchstens 255 Zeichen. Die SDKs erzeugen pro logischem Versand automatisch einen Schlüssel.
unauthorized HTTP 401
Bedeutung: Es wurde kein Schlüssel übergeben oder der Schlüssel lässt sich keiner Organisation zuordnen.
Lösung: Übergeben Sie den öffentlichen Schlüssel als user_id / X-Frontmail-Public-Key oder den privaten Schlüssel als Authorization: Bearer sk_….
invalid_public_key HTTP 401
Bedeutung: Der öffentliche Schlüssel existiert nicht oder wurde erneuert.
Lösung: Kopieren Sie den aktuellen öffentlichen Schlüssel im Dashboard unter Sicherheit → Öffentlicher Schlüssel. Veröffentlichen Sie Ihre Website nach einer Erneuerung mit dem neuen Schlüssel.
invalid_private_key HTTP 401
Bedeutung: Der private Schlüssel ist unbekannt oder wurde widerrufen.
Lösung: Erstellen Sie unter Sicherheit → Private Schlüssel einen neuen privaten Schlüssel und aktualisieren Sie das Secret in Ihrer Serverumgebung.
insufficient_credits HTTP 402
Bedeutung: Ihre Organisation hat keine Credits mehr und nutzt den Modus reject. Im Standardmodus hold erhalten Sie stattdessen 202 mit status: "held" – es sei denn, die Warteschlange zurückgehaltener E-Mails ist voll (details.reason: "hold_queue_full", mit held und limit).
Lösung: Kaufen Sie ein Credit-Paket, aktivieren Sie die automatische Aufladung, führen Sie ein Upgrade durch oder wählen Sie unter Sicherheit → Wenn Ihre Credits aufgebraucht sind die Option E-Mails zurückhalten. Bei hold_queue_full geben Sie außerdem zurückgehaltene E-Mails frei oder verwerfen sie. Siehe Warteschlange zurückgehaltener E-Mails.
forbidden HTTP 403
Bedeutung: Der Schlüssel oder Benutzer darf diese Aktion nicht ausführen.
Lösung: Prüfen Sie die Rolle des Teammitglieds oder verwenden Sie für serverseitige Endpunkte einen privaten Schlüssel.
origin_not_allowed HTTP 403
Bedeutung: Die Anfrage kam von einem Origin, der nicht in Ihrer Liste erlaubter Domains steht – oder sie hat gar keinen Origin/Referer (Server, curl, native App) und Mobile Apps erlauben ist deaktiviert. In diesem Fall ist details.reason gleich no_origin.
Lösung: Fügen Sie die Domain (z. B. example.com oder *.example.com) unter Sicherheit → Erlaubte Websites hinzu. Für die lokale Entwicklung brauchen Sie auch localhost. Für native Apps aktivieren Sie Mobile Apps erlauben; auf Servern verwenden Sie statt des öffentlichen einen privaten Schlüssel.
captcha_required HTTP 403
Bedeutung: Die Vorlage verlangt Turnstile, die Anfrage enthielt aber kein Token.
Lösung: Rendern Sie das Turnstile-Widget (die Komponente FrontmailForm für React/Vue/Svelte erledigt das für Sie) oder übergeben Sie turnstile_token. Serverseitige Aufrufe mit privatem Schlüssel überspringen diese Prüfung.
captcha_failed HTTP 403
Bedeutung: Cloudflare hat das Turnstile-Token abgelehnt – es ist ungültig, abgelaufen (Tokens gelten ca. 5 Minuten) oder wurde bereits verwendet. Bei details.reason: "hostname_mismatch" wurde das Widget auf einem anderen Hostnamen gelöst als dem, von dem die Anfrage kam.
Lösung: Setzen Sie das Widget zurück und lassen Sie den Nutzer die Prüfung erneut lösen. Verwenden Sie ein Token nie für mehrere Sendungen. Bei hostname_mismatch tragen Sie alle Hostnamen Ihrer Website (z. B. example.com und www.example.com) in Ihrem Turnstile-Widget bei Cloudflare ein. Siehe Turnstile.
captcha_not_configured HTTP 403
Bedeutung: Die Vorlage verlangt Turnstile, Ihre Organisation hat aber keine eigenen Turnstile-Schlüssel hinterlegt, daher lassen sich Anfragen von Websites nicht prüfen. In der Produktion werden auch Cloudflare-Testschlüssel (1x…, bestehen immer) abgelehnt (details.reason: "test_secret").
Lösung: Erstellen Sie in Ihrem Cloudflare-Konto ein kostenloses Turnstile-Widget und tragen Sie dessen Site Key und Secret Key unter Sicherheit → Bot-Schutz (Turnstile) ein. Oder deaktivieren Sie bei der Vorlage CAPTCHA verlangen (Turnstile). Siehe Turnstile.
headless_blocked HTTP 403
Bedeutung: blockHeadless ist aktiv und die Anfrage stammt offenbar aus einem Headless-Browser.
Lösung: Bei Bots ist das erwünscht. Ist ein echter Nutzer betroffen, deaktivieren Sie blockHeadless bei der SDK-Initialisierung oder Headless-Browser blockieren unter Sicherheit → Schutz vor Missbrauch.
recipient_blocked HTTP 403
Bedeutung: Ein Empfänger oder die überwachte Variable entspricht einem Eintrag auf Ihrer Blockliste.
Lösung: Entfernen Sie den Eintrag unter Sicherheit → Blockliste, falls er versehentlich hinzugefügt wurde.
private_key_required HTTP 403
Bedeutung: Der Endpunkt (Batch, Verlauf, Vorlagen) oder die Einstellung der Organisation erfordert einen privaten Schlüssel.
Lösung: Rufen Sie ihn von Ihrem Server mit Authorization: Bearer sk_… auf – liefern Sie einen privaten Schlüssel niemals an den Browser aus.
private_key_in_browser HTTP 403
Bedeutung: Ein privater Schlüssel (Authorization: Bearer sk_… oder accessToken) wurde mit einem Origin-Header gesendet, also von einer Webseite, auf der ihn jeder Besucher auslesen kann. Private Schlüssel sind Zugangsdaten für Server.
Lösung: Verwenden Sie im Browser den öffentlichen Schlüssel und behalten Sie den privaten auf Ihrem Server. Wenn Sie ihn wirklich im Browser brauchen (internes Tool), aktivieren Sie unter Sicherheit die Option Private Schlüssel im Browser erlauben – und erneuern Sie den Schlüssel, falls er jemals öffentlich war.
email_not_verified HTTP 403
Bedeutung: Der Kontoinhaber hat seine E-Mail-Adresse noch nicht bestätigt. Unbestätigte Konten können das Dashboard ansehen, aber nicht senden.
Lösung: Klicken Sie auf den Link in der Bestätigungs-E-Mail oder lassen Sie sie sich über das Banner im Dashboard erneut senden.
organization_suspended HTTP 403
Bedeutung: Die Organisation wurde gesperrt, meist wegen Missbrauchs oder einer angefochtenen Zahlung.
Lösung: Schreiben Sie von der Adresse des Inhabers an support@frontmail.dev.
plan_limit_reached HTTP 403
Bedeutung: Ein Tariflimit außer den Credits wurde erreicht – Anzahl der Vorlagen, Benutzer oder eine Funktion, die Ihr Tarif nicht enthält. Auch nach einem Downgrade eingefrorene Elemente liefern diesen Fehler – beim Senden und bei Erneut senden im Dashboard (details.reason: "template_frozen").
Lösung: Führen Sie ein Upgrade durch – eingefrorene Vorlagen und Mitglieder werden automatisch wieder freigeschaltet – oder löschen Sie Vorlagen bzw. widerrufen Sie offene Einladungen, um Platz zu schaffen. Siehe Tarife und Tarifwechsel.
dynamic_recipient_not_allowed HTTP 403
Bedeutung: Ein Empfängerfeld (To/CC/BCC) wird aus einem Parameter gebildet, die Vorlage erlaubt aber keine dynamischen Empfänger. Das schützt Sie davor, als offenes Relay missbraucht zu werden.
Lösung: Aktivieren Sie Dynamischen Empfänger erlauben in den Vorlageneinstellungen (Einstellungen → Schutz) nur, wenn Sie es wirklich brauchen und Turnstile sowie erlaubte Domains aktiv sind.
dynamic_recipient_requires_captcha HTTP 403
Bedeutung: Die Vorlage übernimmt den Empfänger aus Parametern und die Anfrage nutzt den öffentlichen Schlüssel, die Vorlage verlangt aber kein CAPTCHA. Ohne CAPTCHA könnte jeder, der Ihren öffentlichen Schlüssel kopiert, Ihre Vorlage an beliebige Adressen senden.
Lösung: Hinterlegen Sie Ihre Cloudflare-Turnstile-Schlüssel unter Sicherheit → Bot-Schutz und aktivieren Sie CAPTCHA verlangen für die Vorlage – oder senden Sie diese Vorlage von Ihrem Server mit einem privaten Schlüssel. Siehe Erlaubte Links & Inhaltssperre.
dynamic_field_not_allowed HTTP 403
Bedeutung: Ein Absenderfeld wird aus Parametern gebildet und die Anfrage nutzt den öffentlichen Schlüssel: Die Absenderadresse darf das nie, bei Vorlagen mit dynamischem Empfänger auch nicht der Absendername oder Reply-To. details.fields listet die Felder auf.
Lösung: Verwenden Sie in der Vorlage feste Werte (die Adresse des Besuchers gehört nur dann in Reply-To, wenn der Empfänger fest ist, z. B. bei einem Kontaktformular) – oder senden Sie von Ihrem Server mit einem privaten Schlüssel.
link_not_allowed HTTP 403
Bedeutung: Die gerenderte E-Mail verlinkt auf eine Domain außerhalb Ihrer erlaubten Link-Domains. Geprüft wird bei Sendungen mit öffentlichem Schlüssel an Vorlagen mit dynamischem Empfänger, bei automatischen Antworten und bei Vorlagen mit Nur Links auf erlaubte Domains zulassen. details.hosts listet die betroffenen Domains auf (nie die vollständige URL).
Lösung: Fügen Sie die Domain unter Sicherheit → Erlaubte Link-Domains hinzu, schreiben Sie den Link direkt in die Vorlage oder entfernen Sie ihn aus den Parametern. Siehe Erlaubte Links & Inhaltssperre.
attachments_not_allowed HTTP 403
Bedeutung: Die Anfrage enthält dynamische Anhänge, aber die Vorlage erlaubt keine, Ihr Tarif enthält keine Anhänge (Free) oder der Dateityp ist gesperrt (ausführbare Dateien, Skripte, Disk-Images, HTML/SVG, Office-Dateien mit Makros). POST /v1/uploads mit dem öffentlichen Schlüssel erfordert außerdem mindestens eine Vorlage, die Anhänge erlaubt.
Lösung: Aktivieren Sie Anhänge aus dem Formular erlauben in den Vorlageneinstellungen und prüfen Sie, ob Ihr Tarif Anhänge enthält.
not_found HTTP 404
Bedeutung: Die URL entspricht keinem Endpunkt.
Lösung: Prüfen Sie den Pfad und das Präfix /v1.
service_not_found HTTP 404
Bedeutung: Die service_id existiert in der Organisation dieses Schlüssels nicht oder es ist kein Standarddienst festgelegt.
Lösung: Kopieren Sie die ID unter E-Mail-Dienste oder legen Sie einen Dienst als Standard fest.
template_not_found HTTP 404
Bedeutung: Die template_id existiert in der Organisation dieses Schlüssels nicht.
Lösung: Kopieren Sie die Vorlagen-ID unter Vorlagen. Schlüssel einer anderen Organisation sehen die Vorlage nicht.
message_not_found HTTP 404
Bedeutung: Die Nachricht existiert nicht, ist älter als die Aufbewahrungsdauer Ihres Verlaufs oder das Status-Token passt nicht.
Lösung: Verwenden Sie message_id und status_token aus der Antwort auf den Versand.
conflict HTTP 409
Bedeutung: Die Ressource wurde parallel geändert oder befindet sich in einem Zustand, der die Aktion nicht zulässt (z. B. Freigabe einer bereits gesendeten Nachricht). Bei details.reason: "subscription_not_active" wurde ein Tarifwechsel abgelehnt, weil für das Abonnement eine Rechnung offen ist.
Lösung: Laden Sie die Ressource neu und versuchen Sie es erneut. Bei subscription_not_active begleichen Sie zuerst die offene Rechnung (Abrechnung → Tarif → Karten & Rechnungen verwalten) und wechseln dann den Tarif.
idempotency_conflict HTTP 409
Bedeutung: Derselbe Idempotency-Key wurde innerhalb von 24 Stunden mit einem anderen Request-Body verwendet.
Lösung: Erzeugen Sie für jeden neuen logischen Versand einen neuen Schlüssel. Verwenden Sie einen Schlüssel nur erneut, wenn Sie exakt dieselbe Anfrage wiederholen.
payload_too_large HTTP 413
Bedeutung: Der Request-Body überschreitet die Größenbeschränkung.
Lösung: Laden Sie große Dateien über Uploads hoch und halten Sie die Parameter klein.
attachment_too_large HTTP 413
Bedeutung: Die Gesamtgröße der Anhänge in einer Anfrage überschreitet das Limit Ihres Tarifs.
Lösung: Komprimieren Sie die Dateien, senden Sie stattdessen einen Link oder führen Sie ein Upgrade durch. Siehe Tarife.
invalid_template_params HTTP 422
Bedeutung: Die Parameter entsprechen nicht dem Schema der Vorlage – ein Pflichtparameter fehlt, ein Wert hat den falschen Typ oder verletzt eine Regel (Länge, Bereich, Muster, Auswahl). Im strikten Modus schlagen auch unbekannte Parameter fehl. Sendungen mit öffentlichem Schlüssel an Vorlagen mit dynamischem Empfänger lehnen zusätzlich HTML-Parameter und Werte über 500 Zeichen ab (details.reason: "content_locked"). details enthält einen Eintrag pro Feld.
Lösung: Korrigieren Sie die in details aufgeführten Felder. Mit npx frontmail types erzeugte Typen fangen solche Fehler schon beim Kompilieren ab.
translation_not_configured HTTP 422
Bedeutung: Eine maschinelle Übersetzung wurde angefordert, aber die Organisation hat keinen API-Schlüssel für einen Übersetzungsanbieter (oder nicht für den gewünschten).
Lösung: Hinterlegen Sie Ihren eigenen OpenAI-, Anthropic-, Gemini- oder DeepL-Schlüssel unter Einstellungen → Maschinelle Übersetzung. Siehe Übersetzungen von Vorlagen.
translation_invalid HTTP 422
Bedeutung: Der Anbieter hat eine Übersetzung geliefert, die die Struktur der Vorlage verändert – ein Handlebars-Ausdruck, ein Link oder eine Bildadresse fehlt oder weicht ab. Es wurde nichts gespeichert.
Lösung: Versuchen Sie es erneut oder mit einem anderen Anbieter bzw. Modell, oder übersetzen Sie die Variante manuell.
translation_provider_auth HTTP 422
Bedeutung: Der Übersetzungsanbieter hat den API-Schlüssel der Organisation abgelehnt (ungültig, abgelaufen oder ohne Zugriff auf das Modell).
Lösung: Ersetzen Sie den Schlüssel unter Einstellungen → Maschinelle Übersetzung oder wählen Sie ein Modell, auf das Ihr Konto Zugriff hat.
template_render_failed HTTP 422
Bedeutung: Handlebars konnte die Vorlage mit diesen Parametern nicht rendern (z. B. #each über etwas, das keine Liste ist, oder ein unbekannter Helper).
Lösung: Öffnen Sie den Vorlageneditor – der Bereich „Prüfungen“ zeigt das Problem. Testen Sie die gleichen Parameter in der Vorschau.
invalid_recipient HTTP 422
Bedeutung: Nach dem Rendern ist ein Wert in To/CC/BCC/Reply-To keine gültige E-Mail-Adresse oder To ist leer.
Lösung: Prüfen Sie die Empfängerfelder der Vorlage und die Parameter, die sie verwenden.
sender_not_configured HTTP 422
Bedeutung: Die E-Mail hat keine Absenderadresse: Die Vorlage hat keine und der E-Mail-Dienst hat keinen Standardabsender (und auch kein verbundenes Konto oder einen SMTP-Benutzernamen in Form einer E-Mail-Adresse als Ersatz). Wird von Testversänden aus dem Dashboard zurückgegeben.
Lösung: Legen Sie in den Diensteinstellungen (E-Mail-Dienste → Dienst) eine Standard-Absenderadresse oder in den Vorlageneinstellungen eine Absenderadresse fest. Bei Amazon SES und den meisten APIs muss die Adresse eine bestätigte Identität sein.
rate_limited HTTP 429
Bedeutung: Zu viele Anfragen für Ihren Tarif, Ihre IP, Ihren Schlüssel oder die Einstellung limitRate – oder die Anomalieerkennung hat Ihre Organisation gedrosselt. details.scope: "recipient" bedeutet, dass der Empfänger heute bereits die maximale Anzahl an E-Mails mit dynamischem Empfänger erhalten hat (Sicherheit → E-Mails pro Empfänger und Tag); details.scope: "uploadbytes" bedeutet, dass das tägliche Upload-Volumen für Uploads mit öffentlichem Schlüssel aufgebraucht ist.
Lösung: Warten Sie Retry-After Sekunden (die SDKs tun das automatisch). Für Massenversand verwenden Sie /v1/send-batch. Siehe Rate Limits.
test_send_limit HTTP 429
Bedeutung: Sie haben alle kostenlosen Testversände aus dem Vorlageneditor für heute aufgebraucht (20 pro Tag).
Lösung: Warten Sie bis morgen (UTC) oder senden Sie eine echte Nachricht über die API.
recipient_suppressed HTTP 451
Bedeutung: Der Empfänger steht nach einem Hard Bounce, einer Beschwerde oder einem manuellen Eintrag auf Ihrer Sperrliste. Es wird kein Credit verbraucht.
Lösung: Entfernen Sie die Adresse nur dann von der Sperrliste, wenn Sie sicher sind, dass sie gültig ist und die Person Ihre E-Mails erhalten möchte.
internal_error HTTP 500
Bedeutung: Bei uns ist etwas fehlgeschlagen.
Lösung: Wiederholen Sie die Anfrage mit demselben Idempotency-Key (sicher, keine Duplikate). Besteht das Problem weiter, prüfen Sie status.frontmail.dev und kontaktieren Sie den Support mit der Request-ID.
provider_error HTTP 502
Bedeutung: Der E-Mail-Anbieter hat bei einem synchronen Vorgang, z. B. einem Diensttest, einen unerwarteten Fehler zurückgegeben.
Lösung: Öffnen Sie den Dienst im Dashboard, um die Meldung des Anbieters zu sehen. Siehe die Anleitungen zu den Anbietern.
translation_provider_error HTTP 502
Bedeutung: Der Übersetzungsanbieter ist fehlgeschlagen oder hat nicht rechtzeitig geantwortet. details.status enthält den HTTP-Status.
Lösung: Versuchen Sie es später erneut. Häufigste Ursache sind Rate Limits oder das Kontingent Ihres Anbieterkontos.
Clientseitige Fehler (SDK)
Diese Codes erzeugen die SDKs selbst, ohne API-Antwort. Der Fehler hat den Status 0.
network_error SDK
Bedeutung: Die Anfrage hat nie eine HTTP-Antwort erhalten – offline, DNS-Fehler, blockiert durch eine Erweiterung oder eine CORS/CSP-Regel. Wurde bereits mit Backoff wiederholt.
Lösung: Prüfen Sie die Verbindung und Ihre Content-Security-Policy (connect-src https://api.frontmail.dev). Bitten Sie den Nutzer, es erneut zu versuchen.
timeout SDK
Bedeutung: Ein Versuch dauerte länger als timeoutMs (Standard 15 s) und auch alle Wiederholungen liefen in ein Timeout.
Lösung: Eine Wiederholung ist sicher – das SDK verwendet denselben Idempotency-Key, es wird also kein Duplikat gesendet.
aborted SDK
Bedeutung: Das in options.signal übergebene AbortSignal wurde ausgelöst.
Lösung: Nichts zu beheben – meist wurde die Komponente entfernt oder der Nutzer hat die Seite verlassen.
invalid_response SDK
Bedeutung: Der Server hat mit etwas geantwortet, das keine JSON-Antwort von Frontmail ist – typischerweise ein Proxy, ein Captive Portal oder eine falsche apiUrl.
Lösung: Prüfen Sie die Option apiUrl und etwaige Proxys zwischen dem Client und api.frontmail.dev.
not_initialized SDK
Bedeutung: send() wurde vor init() und ohne Schlüssel in den Aufrufoptionen aufgerufen.
Lösung: Rufen Sie beim Start einmal init({ publicKey }) auf oder übergeben Sie den Schlüssel als letztes Argument.
private_key_in_browser SDK
Bedeutung: Ein privater Schlüssel (privateKey bzw. accessToken in @frontmail/emailjs-compat) wurde in Code konfiguriert, der im Webbrowser läuft, oder @frontmail/node wurde in eine Seite gebündelt. Jeder Besucher der Seite könnte den Schlüssel kopieren und Ihren Nachrichtenverlauf lesen.
Lösung: Verwenden Sie im Browser den öffentlichen Schlüssel (pk_…) und behalten Sie den privaten auf Ihrem Server. Erneuern Sie den privaten Schlüssel, falls er je auf einer Seite ausgeliefert wurde. Nur für ein internes Tool auf vertrauenswürdigen Rechnern können Sie dangerouslyAllowPrivateKeyInBrowser: true übergeben.