# Fehler

Jeder Fehler der Publisher API kommt im selben Format: `application/problem+json` nach RFC 9457.

```json
{
  "type": "https://docs.kalender-sync.de/en/api/errors/invalid_request",
  "title": "The request is invalid",
  "status": 400,
  "code": "invalid_request",
  "request_id": "req_…",
  "errors": [
    { "field": "end", "code": "end_before_start", "message": "end must not be before start." }
  ]
}
```

| Feld | Bedeutung |
|---|---|
| `type` | Link auf die Erklärung des Fehlers in dieser Doku (englische Fassung). |
| `title` | Kurze Beschreibung des HTTP-Status. |
| `status` | HTTP-Status, wie in der Antwort. |
| `code` | **Stabiler, maschinenlesbarer Fehlercode.** Werte diesen aus, nicht `title` oder `detail`. |
| `detail` | Optional: Erklärung für Menschen, kann sich ändern. |
| `request_id` | Eindeutige ID der Anfrage. Nenne sie, wenn du dich an den Support wendest. |
| `errors` | Nur bei `invalid_request`: alle Feldfehler mit `field`, `code` und `message`. |

Neue Fehlercodes können dazukommen. Behandle unbekannte Codes nach ihrem HTTP-Status: `4xx` heißt „Anfrage korrigieren“, `429` und `5xx` heißt „später wiederholen“.

## Alle Fehlercodes

| Code | Status | Bedeutung |
|---|---|---|
| [`missing_api_key`](https://docs.kalender-sync.de/api/errors/missing_api_key/) | 401 | Kein API-Key in der Anfrage. |
| [`invalid_api_key`](https://docs.kalender-sync.de/api/errors/invalid_api_key/) | 401 | Der API-Key ist ungültig, widerrufen oder abgelaufen. |
| [`insufficient_scope`](https://docs.kalender-sync.de/api/errors/insufficient_scope/) | 403 | Dem Key fehlt die nötige Berechtigung. |
| [`plan_required`](https://docs.kalender-sync.de/api/errors/plan_required/) | 403 | Für diesen Live-Kalender reicht der Tarif nicht. |
| [`calendar_blocked`](https://docs.kalender-sync.de/api/errors/calendar_blocked/) | 403 | Wir haben diesen Kalender gesperrt. |
| [`terms_required`](https://docs.kalender-sync.de/api/errors/terms_required/) | 403 | Für Live-Kalender fehlt deine Zustimmung zu den Zusatzbedingungen. |
| [`invalid_request`](https://docs.kalender-sync.de/api/errors/invalid_request/) | 400 | Die Anfrage ist ungültig. |
| [`invalid_external_id`](https://docs.kalender-sync.de/api/errors/invalid_external_id/) | 400 | Die external_id einer Batch-Operation ist ungültig. |
| [`invalid_cursor`](https://docs.kalender-sync.de/api/errors/invalid_cursor/) | 400 | Der Cursor zum Blättern ist ungültig. |
| [`invalid_idempotency_key`](https://docs.kalender-sync.de/api/errors/invalid_idempotency_key/) | 400 | Der Idempotency-Key ist zu lang. |
| [`idempotency_key_reused`](https://docs.kalender-sync.de/api/errors/idempotency_key_reused/) | 409 | Der Idempotency-Key wurde für eine andere Anfrage benutzt. |
| [`idempotency_in_progress`](https://docs.kalender-sync.de/api/errors/idempotency_in_progress/) | 409 | Die erste Anfrage mit diesem Idempotency-Key läuft noch. |
| [`not_found`](https://docs.kalender-sync.de/api/errors/not_found/) | 404 | Diesen Endpunkt gibt es nicht. |
| [`calendar_not_found`](https://docs.kalender-sync.de/api/errors/calendar_not_found/) | 404 | Kein Kalender mit dieser ID für diesen Key. |
| [`event_not_found`](https://docs.kalender-sync.de/api/errors/event_not_found/) | 404 | Kein Termin mit dieser external_id in diesem Kalender. |
| [`sync_not_found`](https://docs.kalender-sync.de/api/errors/sync_not_found/) | 404 | Kein Full Sync mit dieser ID für diesen Kalender. |
| [`sync_expired`](https://docs.kalender-sync.de/api/errors/sync_expired/) | 409 | Der Full Sync ist abgelaufen. |
| [`sync_completed`](https://docs.kalender-sync.de/api/errors/sync_completed/) | 409 | Der Full Sync ist schon abgeschlossen. |
| [`calendar_limit_reached`](https://docs.kalender-sync.de/api/errors/calendar_limit_reached/) | 409 | Das Konto hat schon so viele Kalender, wie erlaubt sind. |
| [`event_limit_reached`](https://docs.kalender-sync.de/api/errors/event_limit_reached/) | 409 | Der Kalender hat die maximale Zahl an Terminen. |
| [`sequence_mismatch`](https://docs.kalender-sync.de/api/errors/sequence_mismatch/) | 409 | Der Termin hat sich seit der übergebenen Sequence geändert. |
| [`large_delete`](https://docs.kalender-sync.de/api/errors/large_delete/) | 409 | Der Full Sync würde mehr als die Hälfte der Termine löschen. |
| [`invalid_image`](https://docs.kalender-sync.de/api/errors/invalid_image/) | 400 | Kein Bild im Request-Body. |
| [`image_too_large`](https://docs.kalender-sync.de/api/errors/image_too_large/) | 413 | Das Bild ist zu groß. |
| [`unsupported_image_type`](https://docs.kalender-sync.de/api/errors/unsupported_image_type/) | 415 | Das Bild ist kein PNG, JPEG oder WebP. |
| [`payload_too_large`](https://docs.kalender-sync.de/api/errors/payload_too_large/) | 413 | Der Request-Body ist zu groß. |
| [`unsupported_media_type`](https://docs.kalender-sync.de/api/errors/unsupported_media_type/) | 415 | Der Content-Type wird an diesem Endpunkt nicht angenommen. |
| [`rate_limited`](https://docs.kalender-sync.de/api/errors/rate_limited/) | 429 | Zu viele Anfragen. |
| [`internal_error`](https://docs.kalender-sync.de/api/errors/internal_error/) | 500 | Unerwarteter Fehler bei uns. |

Feldfehler innerhalb von `invalid_request` (zum Beispiel `invalid_timezone` oder `unsupported_rrule`) stehen unter [Termine: Validierungsfehler](https://docs.kalender-sync.de/api/events/#validierungsfehler).