# Fehler

> Wie die Emailit-API Fehler meldet. Formate des Antwort-Bodys, HTTP-Statuscodes und ihre Bedeutung sowie Lösungen für die häufigsten Fehlermeldungen.

Die Emailit-API zeigt mit HTTP-Statuscodes an, ob eine Anfrage funktioniert hat. Codes im Bereich `2xx` bedeuten Erfolg, `4xx`-Codes bedeuten, dass sich an der Anfrage etwas ändern muss, und `5xx`-Codes bedeuten, dass auf unserer Seite etwas schiefgelaufen ist. Diese Seite beschreibt die Fehler-Bodys, alle Statuscodes, die die API zurückgibt, und wie Sie die häufigsten Fehler beheben.

## Formate von Fehlerantworten

Jeder Fehler-Body ist ein JSON-Objekt mit dem Feld `error`. Die genaue Form hängt davon ab, wo die Anfrage fehlgeschlagen ist. Schreiben Sie Ihre Fehlerbehandlung so, dass sie zuerst `error` liest, dann `message`, sofern vorhanden, und dann alle zusätzlichen Felder, die der Endpunkt dokumentiert.

### Anfragefehler

Authentifizierungsfehler, Berechtigungsfehler, fehlerhaftes JSON und andere Fehler, die auftreten, bevor ein Endpunkt läuft, verwenden das Standardformat für HTTP-Fehler:

```json
{
  "statusCode": 401,
  "error": "Unauthorized",
  "message": "API key required"
}
```

| Feld | Beschreibung |
| --- | --- |
| `statusCode` | Der HTTP-Statuscode. |
| `error` | Der HTTP-Statustext, etwa `Unauthorized` oder `Forbidden`. |
| `message` | Was schiefgelaufen ist, in verständlicher Sprache. |

### Validierungsfehler

Hat ein Query-Parameter oder Body-Feld den falschen Typ, fehlt es oder liegt es außerhalb des zulässigen Bereichs, lehnt die API die Anfrage mit `400` ab, bevor sie ausgeführt wird, und listet jedes Problem in `details` auf:

```json
{
  "statusCode": 400,
  "error": "Bad Request",
  "message": "Validation error",
  "details": [
    {
      "instancePath": "/limit",
      "schemaPath": "#/properties/limit/maximum",
      "keyword": "maximum",
      "params": { "comparison": "<=", "limit": 100 },
      "message": "must be <= 100"
    }
  ]
}
```

`instancePath` verweist auf das Feld (`/limit`, `/to`, `/attachments/0/filename`), und `message` beschreibt die verletzte Regel. Bei einigen Endpunkten, etwa [E-Mail senden](/de/docs/api-reference/emails/send/), geben diese Fehler nur `{"error": "Bad Request"}` zurück.

### Ressourcenfehler

Fehler, die ein Endpunkt auslöst, etwa bei einem fehlenden Objekt oder einem doppelten Namen, geben `error` und oft `message` zurück:

```json
{
  "error": "Email not found",
  "message": "Email with ID 'em_4KYof1ZzXndZE2VPi0DgULiekG8' not found in your workspace"
}
```

Einige Fehler enthalten zusätzliche Felder, die Ihnen bei der Behebung helfen:

| Feld | Zurückgegeben bei | Enthält |
| --- | --- | --- |
| `existing` | `409`, wenn Sie eine Domain, einen API-Schlüssel, eine Kontaktliste, einen Kontakt oder einen Abonnenten doppelt erstellen | Das bereits vorhandene Objekt, damit Sie stattdessen dieses verwenden können. |
| `usage` | `422`, wenn ein Tariflimit erreicht ist | `used`, `limit` und bei Kontaktlisten `plan`. |
| `required_plan` | `403` mit `error: "plan_required"` | Der niedrigste Tarif, der die Funktion enthält, etwa `pro`. |
| `code` | Einige `403`- und `422`-Fehler | Ein stabiler, maschinenlesbarer Code, etwa `unverified_workspace_recipient` oder `events_offset_too_large`. |
| `missing` | `404` von [Kontakte gesammelt aktualisieren](/de/docs/api-reference/contacts/bulk/) | Die Kontakt-IDs, die nicht gefunden wurden. |

### Validierungsfehler beim Senden

[E-Mail senden](/de/docs/api-reference/emails/send/) und [E-Mail weiterleiten](/de/docs/api-reference/emails/forward/) prüfen die gesamte Nachricht auf einmal und geben alle Probleme in `validation_errors` zurück:

```json
{
  "error": "Validation failed",
  "validation_errors": [
    "Missing required field: subject",
    "Invalid to email address at index 1: ada@example"
  ]
}
```

### Feldfehler

Vorlagen, Kampagnen und Automatisierungen geben Validierungsprobleme nach Feld gruppiert zurück:

```json
{
  "message": "Validation failed",
  "errors": {
    "alias": ["Alias must contain only lowercase letters (a-z), numbers (0-9), underscores (_), and hyphens (-)"]
  }
}
```

### Rate-Limit-Fehler

`429`-Antworten der Sende-Endpunkte enthalten das erreichte Limit und die Wartezeit. Siehe [Rate Limits](/de/docs/api-reference/rate-limits/).

```json
{
  "error": "Rate limit exceeded",
  "message": "Too many requests. Maximum 2 messages per second allowed.",
  "limit": 2,
  "current": 2,
  "retry_after": 1
}
```

## HTTP-Statuscodes

| Code | Bedeutung | Typische Ursachen in der Emailit-API |
| --- | --- | --- |
| `200` | OK | Die Anfrage hat funktioniert. Sendungen, Aktualisierungen, Löschungen und Lesezugriffe geben `200` zurück. |
| `201` | Created | Eine Domain, ein API-Schlüssel, eine Kontaktliste, ein Abonnent, ein Kontakt, eine Vorlage, ein Webhook oder ein anderes Objekt wurde erstellt. |
| `202` | Accepted | Ein hochgeladener DMARC-Bericht wurde zur Verarbeitung angenommen. |
| `204` | No Content | Ein Formular wurde gelöscht. Die Antwort hat keinen Body. |
| `400` | Bad Request | Ungültiges JSON, ein fehlendes Pflichtfeld, ein Wert mit falschem Typ oder außerhalb des zulässigen Bereichs, ein ungültiger `Idempotency-Key` oder keine Felder zum Aktualisieren. |
| `401` | Unauthorized | Der API-Schlüssel fehlt, ist ungültig, wurde gelöscht oder neu generiert, oder ein OAuth-Token ist abgelaufen. Siehe [Authentifizierung](/de/docs/api-reference/authentication/#authentication-errors). |
| `402` | Payment Required | Der Workspace hat nicht genug Credits für die Sendung, das erneute Senden oder die Verifizierung. |
| `403` | Forbidden | Der Scope des Schlüssels erlaubt den Endpunkt nicht, ein auf eine Domain beschränkter Schlüssel hat von einer anderen Domain gesendet, der Workspace ist gesperrt oder noch nicht verifiziert, die Versanddomain ist pausiert, oder die Funktion erfordert einen höheren Tarif. |
| `404` | Not Found | Das Objekt existiert in diesem Workspace nicht, oder ein Vorlagen-Alias hat keine veröffentlichte Version. |
| `409` | Conflict | Ein Objekt mit demselben Namen oder derselben E-Mail-Adresse existiert bereits, oder eine Anfrage mit demselben `Idempotency-Key` läuft noch. |
| `413` | Payload Too Large | Die zusammengesetzte E-Mail ist größer als 40 MB, oder ein hochgeladener DMARC-Bericht ist größer als 10 MB. |
| `422` | Unprocessable Entity | Die Anfrage ist gültig, lässt sich aber gerade nicht ausführen: Die Domain in `from` ist nicht verifiziert, ein Anhang konnte nicht abgerufen werden, der Status der E-Mail erlaubt kein Stornieren oder erneutes Senden, ihr Inhalt wurde bereits gelöscht, oder ein Tariflimit wurde erreicht. |
| `429` | Too Many Requests | Der Workspace hat sein Versandlimit pro Sekunde, sein Tageslimit oder das stündliche Limit für Weiterleitungen erreicht. |
| `500` | Internal Server Error | Auf unserer Seite ist etwas fehlgeschlagen. Wiederholen Sie die Anfrage mit Backoff, und wenden Sie sich an den Support, wenn der Fehler bestehen bleibt. |
| `503` | Service Unavailable | Ein vorübergehender Ausfall einer Abhängigkeit, etwa des Idempotenzspeichers oder der Authentifizierungsdatenbank. Wiederholen Sie die Anfrage mit Backoff. |

## Häufige Fehler und ihre Behebung

| Status | `error` | Ursache | Lösung |
| --- | --- | --- | --- |
| `400` | `Validation failed` | Einer Sendung fehlt `from`, `to`, `subject` oder Inhalt, oder sie enthält eine ungültige Adresse oder einen ungültigen Anhang. | Beheben Sie jeden Punkt, der in `validation_errors` aufgeführt ist. |
| `400` | `Invalid JSON in request body` (in `message`) | Der Body ist kein gültiges JSON. | Prüfen Sie Anführungszeichen und abschließende Kommas, und senden Sie `Content-Type: application/json`. |
| `400` | `Invalid Idempotency-Key` | Der Schlüssel ist länger als 256 Zeichen oder enthält andere Zeichen als Buchstaben, Ziffern, `-` und `_`. | Verwenden Sie eine UUID oder einen ähnlich sicheren Wert. |
| `402` | `Insufficient credits` | Die Credits sind aufgebraucht. Jeder Empfänger kostet einen Credit. | Kaufen Sie Credits oder aktivieren Sie die [automatische Aufladung](/de/docs/billing/auto-refill/). |
| `403` | `Workspace not verified` | Der Workspace ist im Sandbox-Modus, und ein Empfänger ist kein Mitglied des Workspaces. | Beantragen Sie den [Produktionszugang](/de/docs/workspaces/production-access/). |
| `403` | `Domain paused` | Der Versand von dieser Domain ist wegen ihrer [Versandgesundheit](/de/docs/deliverability/sending-health/) pausiert. | Beheben Sie das Bounce- oder Beschwerdeproblem und wenden Sie sich dann an den Support. |
| `403` | `Domain not authorized` | Der API-Schlüssel ist auf eine andere Versanddomain beschränkt. | Senden Sie von der Domain des Schlüssels oder verwenden Sie einen anderen Schlüssel. |
| `403` | `plan_required` | Die Funktion, etwa DMARC-Berichte oder Webhook-Filter, ist in Ihrem Tarif nicht enthalten. | Wechseln Sie in den Tarif aus `required_plan`. |
| `403` | `mjml_alpha` | Die Anfrage erstellt oder ändert MJML oder ruft einen MJML-Endpunkt auf. MJML ist in der Alpha und steht nur dem Emailit-Team offen. | Verwenden Sie einen anderen Editor oder Inhaltstyp. Siehe [MJML-Editoren und API](/de/docs/templates/mjml/#who-can-use-mjml). |
| `404` | `Template not found` | Die Vorlagen-ID existiert nicht, oder der Alias hat keine veröffentlichte Version. | [Veröffentlichen](/de/docs/api-reference/templates/publish/) Sie eine Version der Vorlage. |
| `409` | `… already exists` | Sie haben ein Objekt mit einem Namen oder einer E-Mail-Adresse erstellt, die bereits vergeben ist. | Verwenden Sie das Objekt in `existing` oder wählen Sie einen anderen Namen. |
| `409` | `Idempotency key in progress` | Eine andere Anfrage mit demselben Schlüssel ist noch nicht abgeschlossen. | Warten Sie einen Moment und wiederholen Sie die Anfrage mit demselben Schlüssel. |
| `413` | `Message too large` | Die E-Mail ist einschließlich Anhängen größer als 40 MB. | Senden Sie große Dateien als Links statt als Anhänge. |
| `422` | `Domain not verified` | Die Adresse in `from` gehört nicht zu einer verifizierten Versanddomain dieses Workspaces. | [Verifizieren Sie die Domain](/de/docs/domains/verification/) oder ändern Sie `from`. |
| `422` | `Attachment error` | Die `url` eines Anhangs konnte nicht innerhalb von 30 Sekunden abgerufen werden, ist nicht erreichbar oder ist größer als 25 MB. | Prüfen Sie, ob die URL öffentlich und die Datei klein genug ist, oder senden Sie stattdessen `content`. |
| `422` | `Cannot cancel email`, `Cannot retry email`, `Cannot update email` | Der Status der E-Mail erlaubt die Aktion nicht, ihr geplanter Zeitpunkt ist weniger als 3 Minuten entfernt, oder ihr Inhalt wurde gelöscht. | Prüfen Sie den `status` der E-Mail. Die Regeln finden Sie beim jeweiligen Endpunkt. |
| `422` | `Page is too deep` | Sie haben bei [Events auflisten](/de/docs/api-reference/events/list/) über Offset 2.500 hinaus geblättert. | Grenzen Sie die Ergebnisse mit den Filtern `type` oder `created_at` ein. |
| `429` | `Rate limit exceeded`, `Daily limit exceeded` | Der Workspace hat sein Versandlimit erreicht. | Warten Sie `retry_after` Sekunden. Siehe [Rate Limits](/de/docs/api-reference/rate-limits/). |

## Sicher wiederholen

- Wiederholen Sie Anfragen mit den Antworten `429`, `500` und `503` nach einer Wartezeit. Verwenden Sie den Header `retry-after`, wenn er vorhanden ist, andernfalls exponentielles Backoff. Beispielcode finden Sie unter [Rate Limits](/de/docs/api-reference/rate-limits/#retry-with-backoff).
- Wiederholen Sie Anfragen mit anderen `4xx`-Fehlern nicht unverändert. Sie schlagen auf dieselbe Weise fehl, bis Sie die Anfrage korrigieren.
- Wenn Sie eine Sendung nach einem Timeout oder einem `5xx`-Fehler wiederholen, verwenden Sie denselben [`Idempotency-Key`](/de/docs/api-reference/idempotency/) erneut, damit die E-Mail nicht zweimal gesendet wird.

## Siehe auch

  - [Authentifizierung](/de/docs/api-reference/authentication/): Zugangsdaten, Scopes und alle Authentifizierungsfehler.
  - [Rate Limits](/de/docs/api-reference/rate-limits/): Versandlimits, Header und Backoff.
  - [Idempotenz](/de/docs/api-reference/idempotency/): Sendungen wiederholen, ohne doppelt zu senden.
  - [Anfrage-Logs](/de/docs/logs/request-logs/): Anfrage und Antwort jedes fehlgeschlagenen API-Aufrufs einsehen.

---
Quelle: https://emailit.com/de/docs/api-reference/errors/