Fehler

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:

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

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:

{
  "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, 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:

{
  "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:

Validierungsfehler beim Senden

E-Mail senden und E-Mail weiterleiten prüfen die gesamte Nachricht auf einmal und geben alle Probleme in validation_errors zurück:

{
  "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:

{
  "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.

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

HTTP-Statuscodes

Häufige Fehler und ihre Behebung

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.
• 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 erneut, damit die E-Mail nicht zweimal gesendet wird.

Siehe auch