MailLandDocs
Referenz

Fehlercodes

Vollständige Referenz der Mail.Land-API-Fehlercodes und deren Bedeutungen

Jede Fehlerantwort der MailLand-API enthält ein code-Feld mit einem maschinenlesbaren Fehlercode und ein message-Feld mit einer menschenlesbaren Beschreibung.

Fehlerantwort-Format

Fehlerantwort
{
  "code": "DOMAIN_NOT_VERIFIED",
  "message": "Domain is not verified",
  "timestamp": "2026-02-18T12:35:00Z",
  "traceId": "00-4bf92f3577b34da6a3ce929d0e0e4736-00f067aa0ba902b7-01"
}

Einige Fehler enthalten zusätzliche details:

Fehlerantwort mit Details
{
  "code": "IP_RATE_LIMIT_EXCEEDED",
  "message": "Too many requests from this IP. Retry after 45 seconds.",
  "details": {
    "limit": 300,
    "current": 301,
    "retryAfter": 45,
    "resetAt": "2026-02-18T12:35:00Z"
  }
}

Anfrage-Validierung (400)

Wird zurückgegeben, wenn der Anfragekörper, die Abfrageparameter oder Header fehlerhaft sind oder Pflichtfelder fehlen.

CodeBeschreibung
INVALID_REQUESTAllgemein ungültige Anfrage
VALIDATION_FAILEDEin oder mehrere Felder haben die Validierung nicht bestanden
INVALID_EMAIL_FORMATE-Mail-Adressenformat ist ungültig
WEBHOOK_DESTINATION_NOT_ALLOWEDEine Webhook-URL wird von der Zielrichtlinie abgelehnt: Webhooks werden nur über HTTPS auf Port 443 zugestellt und dürfen nicht auf eigene Server, Adressen oder Hostnamen von MailLand zeigen
MISSING_CONTENTVeraltet seit 2026-04. Verwenden Sie VALIDATION_FAILED: Send-/Scheduled-Endpunkte geben jetzt strukturierte Validierungsfehler zurück.
CONTENT_TOO_LARGE"The message is too large to send: it would exceed the platform's message-size limit. Reduce the HTML, text, attachments or recipients.": Die Nachricht überschreitet das Größenlimit der Plattform. POST /v1/transactional/send und send-batch liefern 413; nichts wird eingereiht. Verkleinern Sie die Nachricht. Beim CSV-Import ist es 400
transactional_recipient_limit_exceededMehr als 5 Empfänger bei einem transaktionalen Zugangsdatensatz (Code in Kleinbuchstaben)
marketing_recipient_limit_exceededMehr als 1.000 Empfänger bei einem Marketing-Zugangsdatensatz (Code in Kleinbuchstaben)
VALIDATION_FAILEDBatch-Versand mit mehr als 10.000 Empfängern
SEND_FAILEDE-Mail-Versandvorgang fehlgeschlagen, einschließlich „alle Empfänger sind unterdrückt"
BATCH_SEND_FAILEDBatch-Versandvorgang fehlgeschlagen
IDEMPOTENCY_KEY_INVALIDIdempotenzschlüssel ist leer, ungültig, länger als 255 Zeichen, oder der Header wurde mehrfach gesendet (nur send/send-batch)
IDEMPOTENCY_KEY_CONFLICTX-Idempotency-Key-Header und Body-Feld idempotencyKey wurden beide gesendet und unterscheiden sich
INVALID_CURSORCursor-Paginierungsparameter ist fehlerhaft
PASSWORD_REQUIREDPasswortbestätigung ist erforderlich
RECIPIENT_SUPPRESSEDEmpfänger befindet sich auf der Unterdrückungsliste

Authentifizierung (401)

Wird zurückgegeben, wenn in der Anfrage Anmeldedaten fehlen oder diese ungültig sind.

CodeBeschreibung
UNAUTHORIZEDX-API-Key fehlt, ist ungültig, abgelaufen oder widerrufen: die API-Key-Middleware gibt in jedem Fall diesen einen Code mit einer beschreibenden message zurück. Sie unterscheidet fehlend/ungültig/abgelaufen/widerrufen nicht per Code. Ein falsches Login-Passwort gibt ebenfalls 401 UNAUTHORIZED zurück.
LOGIN_REQUIREDAnmeldung ist für diesen Vorgang erforderlich

Zwei-Faktor-Authentifizierung

2FA-Fehler geben 400 INVALID_REQUEST mit einer beschreibenden message zurück (z. B. „Invalid code", „2FA is already enabled"). Es gibt keine dedizierten 2FA-Fehlercodes, lesen Sie das Feld message.

Autorisierung (403)

Wird zurückgegeben, wenn der authentifizierte Benutzer keine Berechtigung hat, die angeforderte Aktion durchzuführen.

CodeBeschreibung
FORBIDDENAllgemein verweigert
INSUFFICIENT_PERMISSIONSBenutzer hat nicht die erforderliche Rolle oder Berechtigung
ACCOUNT_SUSPENDEDBenutzerkonto wurde gesperrt
ACCOUNT_DISABLEDBenutzerkonto wurde deaktiviert
ACCOUNT_NOT_ACTIVEBenutzerkonto ist nicht aktiv
IP_NOT_ALLOWEDClient-IP ist nicht in der erlaubten Liste der Anmeldedaten
VALIDATION_CREDENTIAL_REQUIREDFür die E-Mail-Validierungs-Endpunkte ist ein Validierungs-API-Schlüssel erforderlich. Ein Versand- oder Eingangsschlüssel wird abgelehnt; eine angemeldete Sitzung oder ein Schlüssel des Produkts Validierung wird akzeptiert
PLAN_LIMIT_REACHEDPlan-Ressourcenlimit erreicht: Upgrade erforderlich
SENDING_BLOCKEDVerifizierungsstufe des Kontos erlaubt diesen Versand nicht. Hinweis: Die eigene SendingBlocked-Ablehnung der Policy-Engine ist 403; derselbe Code aus dem Raten-/Aufwärm-Policy-Pfad ist 429, siehe Abschnitt Policy-Engine unten.
SUBSCRIPTION_EXPIREDAbonnement ist abgelaufen
NO_ACTIVE_SUBSCRIPTIONKein aktives Abonnement gefunden
TENANT_APPROVAL_REQUIREDDas Konto wartet vor dem Versand auf eine Prüfung. Wiederholen hilft nicht; wenden Sie sich an den Support
MARKETING_NOT_YET_ALLOWEDMarketing-Versand ist noch nicht freigeschaltet. Er öffnet sich automatisch bei sauberer Transaktionshistorie (mindestens 500 zugestellte Transaktions-E-Mails über mindestens 7 Tage, Hard Bounces unter 2 %, Beschwerden unter 0,1 %)
MARKETING_SUSPENDEDMarketing-E-Mail ist plattformweit vorübergehend nicht verfügbar. Transaktions-E-Mail ist nicht betroffen; Kampagnen und Automationen bleiben erhalten und laufen weiter, sobald Marketing wieder aktiv ist
ACTION_REQUIREDBenutzeraktion erforderlich, bevor der Versand fortgesetzt werden kann. Wird auch für jeden Versand zurückgegeben, solange für den Workspace eine aktive Deliverability-Sperre besteht (Bounce-/Beschwerderate überschritten): das SMTP-Relay gibt für dieselbe Sperre 550 zurück. Siehe Deliverability-Sperren

Nicht gefunden (404)

Wird zurückgegeben, wenn die angeforderte Ressource nicht existiert oder zu einem anderen Workspace gehört.

CodeBeschreibung
RESOURCE_NOT_FOUNDAllgemein: Ressource nicht gefunden
USER_NOT_FOUNDBenutzer existiert nicht
WEBHOOK_NOT_FOUNDWebhook existiert nicht
DELIVERY_NOT_FOUNDWebhook-Zustellung existiert nicht

Die meisten 404-Antworten verwenden den Code RESOURCE_NOT_FOUND. Das Feld message gibt an, welche Ressource nicht gefunden wurde (z. B. "Domain not found", "Template not found", "Campaign not found"). Webhook-Endpunkte sind die Ausnahme: Ein erneuter Zustellversuch verwendet WEBHOOK_NOT_FOUND / DELIVERY_NOT_FOUND.

Konflikt (409)

Wird zurückgegeben, wenn der Vorgang mit dem aktuellen Zustand der Ressource in Konflikt steht.

CodeBeschreibung
CONFLICTAllgemeiner Ressourcenkonflikt
IDEMPOTENCY_KEY_REUSEDIdempotenzschlüssel wird bereits für einen anderen Endpunkt dieses Kontos verwendet (nur send/send-batch)

Domain und Versand (422)

Wird zurückgegeben, wenn die Anfrage formal korrekt ist, aber aufgrund von Geschäftslogik-Einschränkungen nicht verarbeitet werden kann.

CodeBeschreibung
DOMAIN_NOT_FOUNDDomain existiert nicht im Workspace
DOMAIN_NOT_VERIFIEDDomain wurde nicht verifiziert: DNS-Einrichtung zuerst abschließen
DOMAIN_NOT_ALLOWED_FOR_CREDENTIALAnmeldedaten sind für diese Absenderdomain nicht autorisiert
CAMPAIGN_LINK_BLOCKEDEin Link in einer Kampagne zeigt auf ein als unsicher eingestuftes Ziel; die Kampagne wird nicht geplant oder gesendet
DOMAIN_SUSPENDEDDomain wurde gesperrt
DOMAIN_VERIFICATION_EXPIREDDomain-Verifizierung ist abgelaufen: erneut verifizieren

Zahlung erforderlich (402)

Wird zurückgegeben, wenn das Guthaben des Workspace den angeforderten Vorgang nicht abdeckt.

CodeBeschreibung
INSUFFICIENT_CREDITSNicht genügend Guthaben für den Vorgang

Ratenbegrenzung (429)

Wird zurückgegeben, wenn die Anfrage Ratenbegrenzungen überschreitet. Enthält meist den Retry-After-Header; fehlt er, mit exponentiellem Backoff erneut versuchen statt keine Wartezeit anzunehmen.

API-Ratenbegrenzungen

CodeBeschreibung
RATE_LIMIT_EXCEEDEDAllgemeine API-Ratenbegrenzung überschritten
IP_RATE_LIMIT_EXCEEDEDIP-basierte Ratenbegrenzung überschritten
SUPPORT_RATE_LIMITEDSupport-API-Ratenbegrenzung überschritten
TOO_MANY_LOGIN_ATTEMPTSZu viele fehlgeschlagene Anmeldeversuche: vorübergehend gesperrt

E-Mail-Versand-Ratenbegrenzungen

CodeBeschreibung
DAILY_LIMIT_EXCEEDEDTägliches E-Mail-Versandlimit überschritten
WARMUP_LIMIT_EXCEEDEDDas tägliche Anlauflimit Ihres Kontos für neuen Versand ist erreicht; Zurücksetzung um 00:00 UTC (siehe IP-Warmup)
PAYMENT_DAILY_LIMIT_EXCEEDEDTageslimit bei überfälligem Konto erreicht

Plattformkapazität (429)

Diese Ablehnungen bedeuten, dass gerade die Plattform und nicht Ihr Kontingent neue Sendungen begrenzt. Jede ist ein 429 mit Retry-After-Header, nichts wurde eingereiht, und eine Wiederholung derselben Anfrage ist sicher. Über SMTP sind es vorübergehende 421 Try again later: <message>. Die message ist der englische Text, den die API zurückgibt.

Codemessage (wie zurückgegeben)Wann wiederholen
WARMUP_POOL_BUDGET_EXCEEDED"Sending is temporarily paused for today. It resumes automatically at 00:00 UTC; no action is needed."Nach Retry-After (nächste 00:00 UTC)
WARMUP_POOL_BUDGET_EXCEEDED"Sending is briefly delayed. Please retry in a few minutes." (gleicher Code, wenn die Plattformkapazität kurzzeitig nicht prüfbar ist)Nach dem kurzen Retry-After
WARMUP_POOL_EMPTY"Sending is temporarily paused. It resumes automatically; no action is needed."Nach Retry-After; keine Aktion nötig
PLATFORM_DAILY_CAPACITY_REACHED"Platform sending capacity for today is fully booked. This is a temporary platform-wide limit, not your account quota, and it resets at midnight UTC."Nach Retry-After (nächste 00:00 UTC)
PLATFORM_CAPACITY_PROTECTION"New sending is briefly paused to protect platform capacity. Mail already accepted is not affected. This is transient and clears on its own; retry shortly."Nach dem kurzen Retry-After
PROBATION_CAP_REACHED"New accounts can send to N recipients per rolling 24 hours until our team has reviewed the account. Capacity returns as earlier sends age out of the 24-hour window; contact support to request a review." (oder „…cannot be verified right now, so sending is briefly paused…“ bei kurzer Störung)Nach Retry-After oder Prüfung beim Support anfragen

Bereits angenommene E-Mails sind nie betroffen. Behandeln Sie sie wie jedes andere 429: Backoff, Retry-After beachten, erneut versuchen. Es gibt nichts zu konfigurieren oder upzugraden.

Stream-Limits

transactional_recipient_limit_exceeded und marketing_recipient_limit_exceeded sind 400, nicht 429, siehe Abschnitt Anfrage-Validierung oben. BATCH_NOT_ALLOWED_FOR_TRANSACTIONAL ist ebenfalls 400: ein Batch-Versand ist bei einem transaktionalen Zugangsdatensatz unabhängig von Ratenbegrenzungen nicht erlaubt.

Kontingent und Abrechnung

CodeBeschreibung
QUOTA_EXCEEDEDNutzungskontingent für den aktuellen Abrechnungszeitraum überschritten

Policy-Engine

CodeBeschreibung
SENDING_BLOCKEDDie Raten-/Aufwärm-Policy-Engine hat diesen Versand blockiert: Verifizierungsstufe, die Sandbox-Allowlist, eine Kontobeschränkung oder ein ungewöhnlicher Volumenanstieg
MARKETING_PAUSEDMarketing-E-Mails sind für diesen Workspace pausiert

Serverfehler (5xx)

CodeHTTP-StatusBeschreibung
INTERNAL_ERROR500Unerwarteter interner Serverfehler
AUTHENTICATION_FAILED500API-Key-Validierung ist intern fehlgeschlagen (kein falsches Login, erneut versuchen)
TIMEOUT504Vorgang hat das Zeitlimit überschritten
SERVICE_UNAVAILABLE503Dienst ist vorübergehend nicht verfügbar
DATABASE_ERROR503Datenbankfehler aufgetreten

Serverfehler (5xx) sind vorübergehend. Wiederholen Sie die Anfrage mit exponentiellem Backoff. Wenn der Fehler weiterhin besteht, prüfen Sie die MailLand-Statusseite oder kontaktieren Sie den Support.

Fehlerbehandlung

Retry-Strategie

HTTP-StatusErneut versuchen?Strategie
400NeinAnfrage korrigieren und erneut versuchen
401NeinAnmeldedaten prüfen oder Token erneuern
403NeinBerechtigungen überprüfen oder Plan upgraden
404NeinRessourcen-ID prüfen
409NeinKonflikt auflösen
422NeinGeschäftslogik-Problem beheben (z. B. Domain verifizieren)
429JaAuf die Retry-After-Dauer warten, dann erneut versuchen
500JaRetry mit exponentiellem Backoff (max. 3 Versuche)
503JaRetry mit exponentiellem Backoff (max. 5 Versuche)

Ratenbegrenzungs-Header lesen

Die meisten Antworten enthalten X-RateLimit-Limit und X-RateLimit-Remaining:

HeaderBeschreibung
X-RateLimit-LimitMaximal erlaubte Anfragen im aktuellen Zeitfenster
X-RateLimit-RemainingVerbleibende Anfragen im aktuellen Zeitfenster

Ein IP-basiertes 429 fügt zusätzlich hinzu:

HeaderBeschreibung
X-RateLimit-ResetISO-8601-UTC-Zeitstempel, wann das aktuelle Zeitfenster zurückgesetzt wird (nur bei IP-Ratenbegrenzungsantworten)
Retry-AfterSekunden bis zum nächsten Versuch

Nächste Schritte

Marketing

Lists, subscribers, segments, campaigns and automations.

Ratenbegrenzungen

Verstehen Sie API-Ratenbegrenzungen, E-Mail-Versandlimits und den Umgang mit ratenbegrenzten Antworten

Auf dieser Seite

Fehlerantwort-FormatAnfrage-Validierung (400)Authentifizierung (401)Zwei-Faktor-AuthentifizierungAutorisierung (403)Nicht gefunden (404)Konflikt (409)Domain und Versand (422)Zahlung erforderlich (402)Ratenbegrenzung (429)API-RatenbegrenzungenE-Mail-Versand-RatenbegrenzungenPlattformkapazität (429)Stream-LimitsKontingent und AbrechnungPolicy-EngineServerfehler (5xx)FehlerbehandlungRetry-StrategieRatenbegrenzungs-Header lesenNächste Schritte